Forem: Jamal

Transactional Emails in Convex with Bluefox and AWS SES

Jamal — Wed, 23 Apr 2025 13:13:05 +0000

Introduction
Setting Up Bluefox with Convex
1. Create a Bluefox Account and Project
2. Configure Your Environment
3. Install and Run Convex Locally
Integrating Bluefox with Convex Actions
1. Setting Up the Bluefox Client
2. Sending Transactional Emails
3. Sending Triggered Emails
4. Error Handling Best Practices
5. Where to Trigger Emails (Mutations → Actions)
Advanced: Handling Webhooks
1. Features of Bluefox Webhooks
2. Setting Up Bluefox Webhooks
3. Verifying Webhook Requests
Production Deployment Best Practices for Bluefox
Troubleshooting Common Issues
Conclusion

Introduction

Bluefox is a modern email API built on top of Amazon SES, designed for developers and SaaS teams. Whether you’re sending transactional emails or integrating real-time webhooks in a serverless Convex backend, Bluefox simplifies the process. By wrapping a usage-based, developer-friendly API around Amazon SES, you get excellent deliverability and scalability, without the complexity of managing SES directly.

For Convexdevelopers, Bluefox integrates seamlessly with Convex actions, which make external calls to the Internet. This guide will walk you through setting up Bluefox with Convex, integrating it into your codebase, handling Bluefox webhooks, and outlining key considerations for deploying to production.

Setting Up Bluefox with Convex

1. Create a Bluefox Account and Project

Sign Up: Visit bluefox.email and create a new account.
Add a Project: Once inside your dashboard, create a new Project.
Connect AWS SES: Add a sending email address and link your AWS SES credentials (an IAM user with ses:SendEmail, ses:SendRawEmail, ses:GetSendQuota, ses:ListIdentities permissions).
Automatic Management: Bluefox handles sending queues, email rendering, and analytics for you.

2. Configure Your Environment

Obtain your API key from the Bluefox project settings. Then add BLUEFOX_API_KEY to your environment variables (via the Convex dashboard).

3. Install and Run Convex Locally

npm install convex
npx convex dev

This installs Convex locally, ensuring any changes sync with the Convex cloud.
(Note: Check npmjs.com for the latest bluefox-email version.)

Integrating Bluefox with Convex Actions

Convex organizes backend logic into queries, mutations, and actions. Only actions can perform external HTTP requests, making them ideal for sending emails via Bluefox.

Setting Up the Bluefox Client

Install the bluefox-email TypeScript library, which provides a typed interface, robust error handling, and webhook utilities:

npm install bluefox-email

Then create a reusable client (e.g., convex/bluefox.ts):

// convex/bluefox.ts
import { BluefoxClient } from "bluefox-email";

// Initialize the Bluefox client with your API key
export const bluefox = new BluefoxClient({
  apiKey: process.env.BLUEFOX_API_KEY!, // Ensure set in Convex dashboard
  debug: true // Optional debug logs
});

Sending Transactional Emails

Below is an example of sending a welcome email when a user signs up:

// convex/actions/sendWelcomeEmail.ts
import { internalAction } from "./_generated/server";
import { v } from "convex/values";
import { bluefox } from "../bluefox";

// Sends a welcome email using a transactional template
export const sendWelcomeEmail = internalAction({
  args: { email: v.string(), name: v.string() },
  handler: async (_ctx, { email, name }) => {
    const result = await bluefox.email.sendTransactional({
      to: email,
      transactionalId: "welcome-email", // Configured in the Bluefox dashboard
      data: { name }
    });

    if (!result.ok) {
      console.error("Failed to send welcome email:", result.error.message);
    }
  },
});

The transactionalId maps to a pre-configured template in your Bluefox dashboard, and the data object passes dynamic fields (e.g., {name}).

Sending Triggered Emails

Triggered emails are ideal for automated lifecycle messages, such as re-engagement:

// convex/actions/sendReengagementEmail.ts
import { internalAction } from "./_generated/server";
import { v } from "convex/values";
import { bluefox } from "../bluefox";

// Sends an automated re-engagement email based on user inactivity
export const sendReengagementEmail = internalAction({
  args: { email: v.array(v.string()), lastActiveDate: v.string() },
  handler: async (_ctx, { emails, lastActiveDate }) => {
    await bluefox.email.sendTriggered({
      emails,
      triggeredId: "reengagement-email", // Configured in Bluefox dashboard
      data: { lastActive: lastActiveDate }
    });
  },
});

Error Handling Best Practices

bluefox-email returns a Result type for safer handling:

const result = await bluefox.email.sendTransactional({ ... });

if (!result.ok) {
  switch (result.error.code) {
    case "VALIDATION_ERROR":
      console.error("Invalid email data:", result.error.message);
      break;
    case "RATE_LIMIT_ERROR":
      console.error("Too many requests, try again later");
      break;
    default:
      console.error("Unexpected error:", result.error.message);
  }
}

Where to Trigger Emails (Mutations → Actions)

To maintain data consistency, use Convex mutation functions to call email-sending actions:

// convex/mutations/createUser.ts
import { mutation, internal } from "./_generated/server";
import { v } from "convex/values";

// Creates a new user record and then sends a welcome email
export const createUser = mutation({
  args: { email: v.string(), name: v.string() },
  handler: async (ctx, { email, name }) => {
    await ctx.db.insert("users", { email, name });
    // Schedule the welcome email to be sent after user creation
    await ctx.scheduler.runAfter(0, internal.actions.sendWelcomeEmail, {
      email,
      name,
    });
  },
});

Advanced: Handling Webhooks

Bluefox supports webhooks for real-time event notifications (opens, clicks, bounces, complaints). This allows you to track user interactions directly within your Convex application.

Features of Bluefox Webhooks

Real-Time Updates: Receive immediate data about user activity.
Customizable Events: Choose which events you want to listen for.
Secure Communication: Validate incoming requests via API keys.
Easy Integration: Works seamlessly with Convex’s actions or httpAction endpoints.

Setting Up Bluefox Webhooks

Navigate to Webhooks: In your Bluefox Project Settings, find Webhooks.
Add Webhook URL: Provide a Convex httpAction endpoint URL to handle POST requests.
Select Events: Choose the events you want to track (opens, clicks, bounces, etc.).
Secure Your API Key: After saving, note the key you’ll use to validate requests.
Test Your Endpoint: Use the “Test Webhook” feature to confirm everything is working.

(For more details, see the Bluefox Webhook Docs.)

Verifying Webhook Requests

Webhook calls include an API key in the Authorization header (e.g., Bearer YOUR-SECRET-KEY). Verify that key against your stored keys.

// convex/httpActions/webhookHandler.ts
import { httpAction } from "./_generated/server";
import { bluefox } from "../bluefox";

// Handles incoming Bluefox webhook events
export const handleBluefoxWebhook = httpAction(async ({ request }) => {
  try {
    // Validate the webhook using one or more valid keys
    await bluefox.webhooks.validateWebhook({
      request,
      validApiKeys: ["primary-key", "secondary-key"]
    });

    // Parse the incoming event for further processing
    const event = await bluefox.webhooks.parseWebhookEvent(request);

    switch (event.type) {
      case "open":
        console.log(`Email opened by ${event.emailData?.to}`);
        break;
      case "click":
        console.log(`Link clicked: ${event.link}`);
        break;
      case "bounce":
        console.warn(`Email bounced: ${event.emailData?.to}`);
        break;
      // Handle other event types as needed
    }

    return new Response("OK", { status: 200 });
  } catch (error) {
    console.error("Webhook validation failed:", error);
    return new Response("Invalid webhook", { status: 400 });
  }
});

Production Deployment Best Practices for Bluefox

1. Configure Environment Variables per Deployment Stage

When deploying to different Convex environments (dev, staging, production), you’ll want to isolate your email configurations:

Use Distinct API Keys: Create a separate Bluefox project (and associated API key) for each environment. This prevents test emails from accidentally sending to live users and keeps each environment’s data, template settings, and analytics separate.
Secure Access in Convex: Store BLUEFOX_API_KEY and other sensitive credentials (like AWS Access Keys) in the Convex Dashboard’s environment settings. This avoids checking secrets into version control and ensures only authenticated project members can update them.

Proper isolation reduces risk. If your staging environment’s email-sending logic has a bug, you don’t risk spamming real users or impacting your production deliverability.

2. Leverage Bluefox's Multi-Environment Support

Bluefox makes it easy to manage multiple projects—one for each environment:

Separate Projects: Create a “Dev” project, a “Staging” project, and a “Production” project in the Bluefox dashboard. This way, each environment has its templates, sender identities, and analytics.
Template & Data Separation: By segregating templates, you can safely experiment with design or copy changes in a non-production environment without risking your live email campaigns.

This approach ensures a clear boundary between testing and live operations. It also simplifies debugging—if something fails in dev, you know exactly which key and project to inspect.

3. Ensure AWS SES Production Access

Bluefox relies on your AWS SES credentials, so you need to move out of the “sandbox” mode:

Domain Verification: Verify your domain in the AWS SES console. This adds DNS records (SPF, DKIM) that prove you own the domain.
Request Production Access: AWS requires a justification for sending emails outside the sandbox. Be clear about your use cases (transactional vs. marketing) and compliance practices in your support request.
Monitor Sending Limits: Even in production, AWS imposes sending limits based on your account’s trust level. Keep an eye on your quota to avoid hitting a cap mid-campaign.

Proper SES configuration is essential for deliverability. If you forget to verify your domain or finalize production access, your emails may never leave the sandbox—or worse, land in spam.

4. Implement Bounce and Complaint Handling

Maintaining a good sender reputation is critical for high delivery rates:

Real-Time Monitoring: Configure webhooks for bounce and complaint events in Bluefox. This allows your app to react immediately when an email fails or a user marks it as spam.
Automated Suppression: Whenever you receive a bounce or complaint event, mark the email address as “unreachable” in your database. Sending again to these addresses can harm your domain reputation.
User Feedback Loop: Consider notifying users with outdated or invalid emails to update their information.

Unchecked bounces and spam complaints degrade your sender reputation. Over time, this can lead to your emails being blocked or flagged as spam by major providers.

5. Authenticate Your Domain with SPF, DKIM, and DMARC

Proper domain authentication is crucial for email security and deliverability:

SPF (Sender Policy Framework): Specifies which servers can send email on behalf of your domain.
DKIM (DomainKeys Identified Mail): Uses cryptographic signatures to prove an email came from your domain.
DMARC (Domain-based Message Authentication, Reporting, and Conformance): Builds on SPF and DKIM, telling receiving mail servers how to handle unauthenticated messages and providing feedback via DMARC reports.

These protocols prevent spoofing and boost trust. Many email providers (Gmail, Outlook, etc.) use authentication checks to decide if an email goes to the inbox or spam folder.

6. Provide Unsubscribe and Preference Management

Even if you’re mostly sending transactional messages, giving users control over what they receive is beneficial:

Unsubscribe Links: For marketing or optional notifications, link users to a page where they can opt out.
Preference Center: Provide a central place where users can pause certain emails or change frequency.
Legal Compliance: Regulations like CAN-SPAM (in the US) and GDPR (in the EU) often require some form of opt-out for marketing emails.

Offering an easy way to unsubscribe or pause notifications reduces spam complaints and legal exposure. It also builds user trust by respecting their communication preferences.

7. Monitor and Optimize Your Email Metrics

Simply sending emails isn’t enough—continuous monitoring is key:

Track Delivery, Open, and Click Rates: Bluefox offers dashboards to view engagement metrics in near real-time.
Analyze Bounces and Complaints: A sudden spike can indicate deliverability issues or a poorly targeted list.
A/B Testing Templates: Experiment with subject lines, content, and send times. Then compare open/click rates to refine your approach.

Ongoing analytics help you spot red flags early (e.g., deliverability drops). They also guide iterative improvements, ensuring your email performance keeps pace with user needs and business goals.

Conclusion

Bluefox is an excellent choice for anyone building a SaaS on Convex who needs a robust, developer-friendly email platform. By abstracting away the complexity of Amazon SES, it lets you focus on crafting great user experiences while still benefiting from SES’s world-class deliverability. Set up your Bluefox project, follow these best practices for webhooks and production, and you’ll be sending modern, scalable emails in no time!

Authentication Best Practices: Convex, Clerk and Next.js

Jamal — Thu, 06 Mar 2025 19:53:30 +0000

Authentication is the backbone of any full-stack application, but it’s also one of the easiest places to introduce subtle, hard-to-debug security flaws. As developers, we aim to build secure, reliable systems, but scaling an app to a global audience presents unique challenges—especially regarding authentication.

At ClarityText, where we use Convex in production, we ran into unexpected authentication issues that affected a significant number of users. The problem stemmed from how we handled authentication checks in our client-side application.

Our app relies on the useConvexAuth() hook to verify user sessions on the client. The useConvexAuth() hook returns a promise that needs to be awaited—meaning other React hooks, including Convex queries, can start running before authentication is fully validated. The problem arose from the unpredictability of whether authentication would complete before a Convex query executed. This introduced a race condition where unauthenticated requests could slip through, causing security risks and a frustrating user experience.

In this post, I’ll share what we learned about Convex authentication, how it integrates with Clerk, and best practices for handling authentication effectively. We’ll break down race conditions—what they are, why they happen, and the risks they pose. Then, I’ll introduce three key rules to help you prevent these issues when using Convex and Clerk. To wrap things up, I’ll provide custom hooks that you can easily implement to create safer, more reliable authentication flows in your applications.

Where Does Authentication Belong in Your Application?

Authentication isn’t just about verifying users—it’s about ensuring security at every layer of your application.
When building with Convex, Next.js, and Clerk (or similar tools), authentication needs to be considered at three key levels:

Server-side Authentication – Traditionally, authentication is handled at the backend using middleware. In frameworks like Next.js, middleware runs before API requests are processed, allowing authentication checks to happen early. Clerk, for example, uses middleware to validate user sessions before they reach API routes.
Client-side Authentication – Many web apps require real-time interactions, meaning authentication must also be handled by the client. React hooks like useAuth() from Clerk help verify user sessions in the browser, but client-side authentication alone isn’t secure since frontend code can be manipulated. It’s useful for UI state but shouldn’t be solely relied on for access control.
Database Authentication (Convex) – In a typical backend setup, authentication checks happen at the API level before interacting with a database. But with Convex, your backend is a database and public API. That means authentication checks must be enforced within Convex functions to ensure unauthorized users can’t read or write data.

Each of these layers plays a crucial role in securing your application. Failing to authenticate users at any of
them can lead to vulnerabilities, especially in real-time applications where database queries might execute before
authentication is fully validated.

Implementing Authentication Correctly

When working with authentication, it’s easy to assume that once a user is authenticated at one layer of the application,
they’re secure everywhere. But with Next.js and Convex, authentication needs to be explicitly handled at multiple
points—especially in applications that mix server and client components.

The Hidden Authentication Risk in Next.js

Next.js makes it easy to secure API routes and server components using middleware. However, if a server component
renders a client component that doesn’t properly handle authentication, it can expose parts of your app to unauthorized users.

Consider this example:

Server.tsx

import { ClientComponent } from './client-component';

export const ServerComponent = () => {
  const user_session = { userId: 'user_123' };   // fetch this data from convex or a nextjs cookie

  return <ClientComponent session={user_session} />;
};

export default ServerComponent;

Client.tsx

'use client';

import { api } from '@convex/_generated/api';
import { useQuery } from 'convex/react';

interface Props {
  session: {
    userId: string;
  };
}

export const ClientComponent = ({ session }: Props) => {
  const user = useQuery(api.users.get, { userId: session.userId });

  return <div>{user.password}</div>;
};

export default ClientComponent;

At first glance, this looks fine—middleware ensures the user is authenticated before the server component runs.
However, authentication must still be handled explicitly in client components. If the client-side logic assumes
authentication has already been verified, it could mistakenly expose data or trigger unauthorized Convex queries.

Convex is a Public API by Default.

Unlike traditional databases where queries run directly on your backend server, Convex operates as a public API,
meaning queries are executed over the network. This makes it easy to call Convex functions from client components,
but it also means authentication checks must happen at multiple layers—once on the client and again within Convex’s backend functions.
Since your Next.js server is separate from the Convex backend, securing one doesn’t automatically secure the other.

Use Internal Functions for Increased Security

While public functions are accessible to client-side code, Convex also supports
internal functions that can only be called by other
functions within your Convex project. These are useful for protecting sensitive logic that shouldn't be directly
accessible from the client. By using internal functions, you can minimize the public surface area of your application,
reducing the risk of exposing vulnerable operations to malicious users.

Internal functions are ideal for situations where you need to run more secure, sensitive logic—such as handling
authentication, processing payments, or updating user data—without risking direct client access. They can be invoked
within actions, cron jobs, or other internal logic flows, ensuring that your sensitive operations are kept behind the
security of your backend. However, remember that even with internal functions, you should still validate user permissions
and data integrity to safeguard against potential security flaws.

Ensuring Authentication in Server Components

When using React Server Components, authentication can be enforced entirely on the server, eliminating the need for client-side checks.
This approach ensures that sensitive data is never exposed to the client before authentication is verified. It also allows
us to fetch user-specific data more efficiently, similar to traditional server-side rendering (SSR).

In a Next.js application, middleware can be used to enforce authentication across all server components, ensuring that only
authorized users access certain pages.

Securing Routes with Middleware

Next.js middleware runs before a request reaches a page, allowing us to validate authentication and modify requests.
Using Clerk, we can protect all authenticated routes by checking the user's session and redirecting them if they are not logged in.

Example from Clerk Nextjs docs

import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isProtectedRoute = createRouteMatcher(['/dashboard(.*)', '/forum(.*)'])

export default clerkMiddleware(async (auth, req) => {
  const { userId, redirectToSignIn } = await auth()

  if (!userId && isProtectedRoute(req)) {
    // Add custom logic to run before redirecting

    return redirectToSignIn()
  }
})

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|wo==ff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
}

With this middleware in place, any request to /dashboard or /forum will require authentication.
If a user is not logged in, they will be redirected to the sign-in page automatically.

Fetching User Data in a Server Component

Once authentication is enforced through middleware, we can safely fetch user data within a server component
without worrying about unauthorized access. You should still check authentication within your convex functions.

Example: Next.js Middleware for Authentication

import { api } from "@convex/_generated/api";
import { auth } from "@clerk/nextjs/server";
import { fetchQuery } from "convex/nextjs";

export const ServerComponent = async () => {
  const { userId } = await auth();

  const user = await fetchQuery(api.users.get, { userId });

  return <div>Hello, {user.name}!</div>;
};

export default ServerComponent;

Why This Approach Works?

Middleware handles authentication upfront, ensuring that only authenticated requests reach protected pages.
Server components fetch data securely without exposing queries to the client.
No client-side authentication checks are required, reducing frontend complexity and reducing chance of race conditions.

Consider Other Frameworks and Security Risks

While this example focuses on Next.js, authentication practices vary between frameworks. If you're using Vue, Svelte,
or another React meta-framework (e.g., Remix, Gatsby), you should research how authentication and data-fetching work
in that ecosystem. Some frameworks may have different security risks or best practices for handling authentication,
session management, and data validation. Understanding how your framework manages authentication will help you implement
the most secure and efficient approach for your Convex app.

Ensuring Authentication in Client Components

While we’ve secured our server components, client-side authentication is just as important when handling user interactions
and front-end data fetching. Client components in Next.js can directly interact with Convex, but we must ensure that queries
are only executed when the user is authenticated. This prevents unauthorized requests and protects sensitive user data.

Convex provides the useConvexAuth() hook to manage authentication
state within React components. This hook allows us to track whether the user is authenticated before making any
queries or displaying protected content.

Understanding `useConvexAuth()`

The useConvexAuth() hook provides two key values:

isLoading – A boolean indicating whether the authentication state is still being determined. This helps prevent flashing unauthorized content before authentication is confirmed.
isAuthenticated – A boolean that indicates whether the user is signed in. If true, you can safely proceed with rendering user-specific content and making database queries.

Example: Checking Authentication in a Client Component

'use client';

import { api } from '@convex/_generated/api';
import { useConvexAuth, useQuery } from 'convex/react';

export const ClientComponent = () => {
  const { isLoading, isAuthenticated } = useConvexAuth();

  if (isLoading) return <div>Loading...</div>;
  if (!isAuthenticated) return <div>Not allowed!</div>;

  return <div>Welcome, user!</div>;
};

Setting Up the Convex Authentication Provider

To use useConvexAuth(), you need to ensure that the authentication state is properly managed and passed down
through a provider. In a Next.js app using Clerk, this is handled by the ConvexProviderWithClerk.

Example: Wrapping the App with an Authentication Provider

'use client';

import { ReactNode } from 'react';
import { ConvexReactClient } from 'convex/react';
import { ConvexProviderWithClerk } from 'convex/react-clerk';
import { ClerkProvider, useAuth } from '@clerk/nextjs';

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL);

export default function ConvexClientProvider({ children }: { children: ReactNode }) {
  return (
    <ClerkProvider publishableKey={process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY}>
      <ConvexProviderWithClerk client={convex} useAuth={useAuth}>
        {children}
      </ConvexProviderWithClerk>
    </ClerkProvider>
  );
}

By wrapping the entire application with ConvexClientProvider, authentication data is available throughout the component tree.
This ensures that the authentication state is correctly passed down to all client components.

Skipping Queries When the User is Not Authenticated

Even with proper authentication checks in the UI, we must ensure that Convex queries do not execute before the user’s
authentication state is confirmed on the client side. A common mistake is triggering queries before checking authentication,
which can lead to unnecessary backend calls or even security vulnerabilities.

Convex allows queries to be conditionally skipped using "skip", preventing them from running until authentication is established.

Example: Skipping Queries Until Authentication is Confirmed

'use client';

import { api } from '@convex/_generated/api';
import { useConvexAuth, useQuery } from 'convex/react';

export const ClientComponent = ({ session }: { session: any }) => {
  const { isLoading, isAuthenticated } = useConvexAuth();

  const user = useQuery(
    api.users.get,
    isAuthenticated ? { userId: session.userId } : "skip"
  );

  if (isLoading) return <div>Loading...</div>;
  if (!isAuthenticated) return <div>Not allowed!</div>;

  return <div>{user?.password}</div>;
};

Why This Matters

Prevents unauthorized queries – Requests are only sent when the user is authenticated.
Optimizes performance – Skipping queries reduces unnecessary backend calls.
Avoids race conditions – Ensures authentication is fully resolved before fetching data.

Securing Your Convex Backend

While securing authentication on the client and server is crucial, the final layer of security lies in your Convex backend functions.
Even if a user bypasses frontend checks, your backend must enforce strict authorization to protect your data.

Convex provides built-in authentication methods that allow you to validate user identity before processing any database operations.
By correctly implementing these checks, you can ensure that only authenticated users can access or modify data.

Enforcing Authentication in Convex Functions

Every Convex function—queries, mutations, and actions—receives a context (ctx) object that contains an auth property.
This allows you to verify the authenticated user before executing any logic.

Example: Restricting Access to Authenticated Users

import { mutation } from "./_generated/server";
import { v, ConvexError } from "convex/values"

export const myMutation = mutation({
  args: {
    someData: v.any()
  },
  handler: async (ctx, { someData }) => {
    const identity = await ctx.auth.getUserIdentity();

    if (identity === null) {
      throw new ConvexError("Unauthenticated call to mutation");
    }

    // Proceed with database operations only for authenticated users...
  },
});

**Working with User Identity Fields

When getUserIdentity() is called, it returns a UserIdentity object containing important authentication details. At a minimum, it will always include:

tokenIdentifier – A unique identifier for the user across authentication providers.
subject – The user’s unique ID from the provider.
issuer – The authentication provider that issued the token.

For users authenticated through Clerk or Auth0, additional fields like name, email, and pictureUrl may be available.

Enforcing Authorization with User Records

Authentication alone isn't enough—you also need to verify whether the user has permission to access certain data.
A common approach is to store user records in your database and check their roles or permissions.

Example: Looking Up a User in the Database

export async function getCurrentUserOrThrow(ctx: QueryCtx) {
  const userRecord = await getCurrentUser(ctx);
  if (!userRecord) throw new ConvexError("Can't get current user");
  return userRecord;
}

export async function getCurrentUser(ctx: QueryCtx) {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) return null;
  return await userByTokenIdentifier(ctx, identity.tokenIdentifier);
}

export async function userByTokenIdentifier(ctx: QueryCtx, tokenIdentifier: string) {
  return await ctx.db
    .query('users')
    .withIndex('by_token', (q) => q.eq('tokenIdentifier', tokenIdentifier))
    .unique();
}

This function retrieves the authenticated user’s record from the database. If no record is found, access is denied.

Best Practices for Backend Security

Always validate ctx.auth.getUserIdentity() before performing database operations.
Restrict access by role or permissions when necessary.
Log authentication failures to detect unauthorized access attempts.

Considerations for Other Frameworks

If you’re using a different authentication provider or another framework like Vue or Svelte, be sure to understand how the user state is managed.
Different frameworks may expose authentication details differently, and security risks can vary based on implementation.
Always review your authentication provider’s documentation to ensure best practices.

Simplifying Development with Custom Hooks and Utility Functions

When working with Convex, writing safe, reusable utilities is essential for making backend logic easier to implement and reducing
the risk of misusing complex functions. By creating secure wrappers around common database operations and React hooks, developers
can avoid redundant code while ensuring consistent authentication and error handling.

Custom Backend Utilities: Queries, Mutations, and Actions

Convex allows you to define backend functions like queries, mutations, and actions. To ensure these operations enforce authentication
consistently, we can wrap them in custom utility functions.

Example: Secure Convex Functions with Authentication

import { action, mutation, query } from '../_generated/server';
import {
  customAction,
  customCtx,
  customMutation,
  customQuery,
} from 'convex-helpers/server/customFunctions';
import { AuthenticationRequired } from '../users/utils';

/** Custom query that requires authentication */
export const authQuery = customQuery(
  query,
  customCtx(async (ctx) => {
    await AuthenticationRequired({ ctx });
    return {};
  }),
);

/** Custom mutation that requires authentication */
export const authMutation = customMutation(
  mutation,
  customCtx(async (ctx) => {
    await AuthenticationRequired({ ctx });
    return {};
  }),
);

/** Custom action that requires authentication */
export const authAction = customAction(
  action,
  customCtx(async (ctx) => {
    await AuthenticationRequired({ ctx });
    return {};
  }),
);

/** Checks if the current user is authenticated. Throws if not */
export async function AuthenticationRequired({
  ctx,
}: {
  ctx: QueryCtx | MutationCtx | ActionCtx;
}) {
  const identity = await ctx.auth.getUserIdentity();
  if (identity === null) {
    throw new ConvexError('Not authenticated!');
  }
}

One of the major benefits of extending Convex's base functions is the ability to modify and extend the context.
This allows you to inject additional data or logic before a query, mutation, or action executes. If you have further questions,
I recommend joining the Convex Discord server for community support and discussions.

At a high level, a custom function wraps and calls the base function internally. This provides an opportunity to execute additional
logic before the function runs. In the example above, the return {} statement passes an empty object, meaning Convex will retain its default
context values. However, you can modify this to return additional data, such as a user object, which would allow all your database queries
to access user data without redundant queries.

By structuring your custom functions this way, they become drop-in replacements for your existing queries and mutations while
maintaining full compatibility with Convex's default behavior.

Making React Querying Easier with Custom Hooks

When working with Convex in React, fetching data can become repetitive. To improve developer experience, we can use custom hooks to
abstract complex logic, making queries easier to implement while enforcing authentication.

Using `useQueryWithStatus` for Enhanced Query Information

The convex-helpers package provides makeUseQueryWithStatus, a utility that extends Convex’s useQuery to include additional metadata such as:

status: 'pending' | 'error' | 'success'
isPending: Whether the request is still in progress
isSuccess: Whether the request was successful
isError: Whether an error occurred
error: The error object
data: The data returned from the convex function

Example: Importing and Using `useQueryWithStatus`

import { makeUseQueryWithStatus } from 'convex-helpers/react';
import { useQueries } from 'convex-helpers/react/cache/hooks';

export const useQueryWithStatus = makeUseQueryWithStatus(useQueries);

This utility makes working with queries more intuitive by giving immediate feedback about their status.

Authenticated Query Hooks: Simplifying Authentication Logic

Instead of manually checking if a user is authenticated before running a query in every component,
we can create custom hooks that automatically handle authentication for us.

`useAuthenticatedQueryWithStatus` – Handling Authentication Automatically

import { FunctionReference } from 'convex/server';
import {
  OptionalRestArgsOrSkip,
  useConvexAuth,
  useQueryWithStatus,
} from 'convex/react';

/**
 * A wrapper around useQueryWithStatus that automatically checks authentication state.
 * If the user is not authenticated, the query is skipped.
 */
export function useAuthenticatedQueryWithStatus<
  Query extends FunctionReference<'query'>,
>(query: Query, args: OptionalRestArgsOrSkip<Query>[0] | 'skip') {
  const { isAuthenticated } = useConvexAuth();
  return useQueryWithStatus(query, isAuthenticated ? args : 'skip');
}

Paginated Query Hook: Handling Pagination Securely

For paginated queries, we can extend the same authentication logic:

import {
  PaginatedQueryArgs,
  PaginatedQueryReference,
  useConvexAuth,
  usePaginatedQuery,
} from 'convex/react';

/**
 * A wrapper around usePaginatedQuery that automatically handles authentication state.
 * If the user is not authenticated, the query is skipped.
 */
export function useAuthenticatedPaginatedQuery<
  Query extends PaginatedQueryReference,
>(
  query: Query,
  args: PaginatedQueryArgs<Query> | 'skip',
  options: { initialNumItems: number },
) {
  const { isAuthenticated } = useConvexAuth();
  return usePaginatedQuery(query, isAuthenticated ? args : 'skip', options);
}

Why Use Custom Hooks and Utility Functions?

Good API design and well-structured utility functions are crucial in production environments.
They simplify complex logic, improve maintainability, and make debugging easier—especially when working in a team.
Here’s why investing in custom hooks and utilities pays off:

Encapsulate Complex Logic – Developers don’t need to understand every failure mode or edge case; they just call a function that "just works" without needing to dive into internal details.
Enforce Security by Default – Authentication and permission checks happen in a centralized place, ensuring every function follows security best practices and reducing the risk of human error.
Reduce Boilerplate Code – Avoid copy-pasting authentication and error-handling logic into every function. Instead, these checks happen automatically, keeping code clean and DRY.
Improve Team Collaboration – A well-designed API allows other developers to use your functions without needing deep knowledge of how they work. This makes onboarding easier and speeds up development.
Simplify Debugging and Logging – Wrapping key operations in utilities makes it easier to log errors consistently, trace issues, and update logic in one place without refactoring multiple files.

Flexible And Secure Development

In production, good API design isn’t just about convenience—it’s about preventing costly mistakes and improving long-term maintainability.
Investing in structured, reusable utilities will save time, reduce bugs, and keep your application secure in the long run.

One Last Commit Before We Ship

At the end of the day, good API design isn’t just about making life easier—it’s about making sure you don’t wake up at 2 AM because someone
forgot an authentication check. By structuring your backend utilities and React hooks properly, you’re not just writing code—you’re writing
code that others will thank you for.

A well-designed API keeps things predictable, maintainable, and secure, making collaboration smoother and debugging less of a nightmare.
It’s the difference between confidently shipping a feature and spending hours in a Slack thread trying to figure out why that one function call only works on Bob’s machine.

And remember: race conditions aren’t just a problem in concurrent programming. They also happen in real life—like when two developers both
deploy a fix at the same time and accidentally roll back the one that actually worked.

So take your time, build smart utilities, and design APIs that make everyone’s job easier. Your future self (and your teammates) will thank you. 🚀

Building Type-Safe Rust Applications with Convex: Introducing convex-typegen

Jamal — Wed, 26 Feb 2025 02:12:03 +0000

If you've been following the backend-as-a-service landscape, you've likely heard of Convex. This innovative platform has been turning heads by offering a unique combination of developer experience, serverless functions, and real-time subscriptions, all wrapped in a developer-friendly package. What makes Convex particularly interesting is that under the hood, it's powered by Rust – a language choice that speaks volumes about its commitment to performance and reliability.

Speaking of Rust, it's fascinating to see how this systems programming language has found its way into backend development. While traditionally associated with low-level programming, Rust has become increasingly popular for building backend services, and for good reason. Its zero-cost abstractions, memory safety guarantees, and fearless concurrency make it an excellent choice for building high-performance, reliable services. Companies like Discord, Dropbox, and Cloudflare have all embraced Rust for critical backend components, proving its worth in production environments.

The relationship between Convex and Rust runs deep. Not only is Convex's core written in Rust, but they also provide first-class support for Rust developers through their official client library. This makes perfect sense – if you're building applications that demand both real-time capabilities and high performance, the combination of Convex's infrastructure and Rust's efficiency is hard to beat.

However, there was one piece missing from this otherwise perfect puzzle: type safety between your Convex backend and Rust frontend. While TypeScript developers enjoyed seamless end-to-end type safety with Convex, Rust developers had to manually maintain their types. That's where our journey begins – creating convex-typegen, a tool that brings the same level of type safety and developer experience to the Rust ecosystem.

Pain Points

When building applications with Convex, type safety is crucial for catching errors early and providing a great developer experience. TypeScript developers have it easy – Convex's TypeScript SDK automatically generates type definitions that perfectly match their backend schema and functions. This means they get real-time type checking, autocomplete suggestions, and compile-time guarantees that their code will work as expected.

For Rust developers, however, the story was different. Despite Rust being one of the most type-safe languages available, integrating with Convex required manually defining and maintaining types that mirror the backend schema. This manual process was not only tedious but also error-prone. Imagine updating a field in your Convex schema and then having to track down every Rust type that needs updating – it's the kind of maintenance burden that can slow down development and introduce subtle bugs.

Let's look at a concrete example. Consider this simple Convex schema:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  messages: defineTable({
    body: v.string(),
    userId: v.id("users"),
  }),
  users: defineTable({
    name: v.string(),
    tokenIdentifier: v.string(),
  }).index("by_token", ["tokenIdentifier"]),
});

Before convex-typegen, Rust developers had to manually maintain corresponding types:

#[derive(Debug, Clone)]
struct MessageDocument
{
    body: String,
    userId: String,
}

#[derive(Debug, Clone)]
struct UserDocument
{
    name: String,
    tokenIdentifier: String,
}

This manual mapping becomes even more complex when dealing with:

Nested objects and arrays
Optional fields
Union types
Custom validators
Function arguments and return types

What we needed was a tool that could automatically generate these Rust types, keeping them in perfect sync with the Convex backend, while respecting Rust's strong type system and idioms. This would not only eliminate the manual maintenance burden but also provide the same level of type safety that TypeScript developers enjoy.

Options I Considered

Before building convex-typegen, I explored using a generic JSON approach to manage type maintenance. This method leverages the flexibility of JSON to dynamically handle data without predefined types. In Rust, this can be achieved using the Value type from the serde_json crate, which allows you to work with JSON data in a type-agnostic manner.

use serde_json::Value;

However, when working with Convex, you have the option to use Convex's own Value type, which is specifically designed to represent the various data types supported by Convex's API. This type provides a more seamless integration with Convex's functions and can be a more idiomatic choice when interacting with Convex services.

use convex::Value as ConvexValue;

Example: Building a Message with Convex's `Value` Type

Consider the following MessageDocument struct that matches your schema:

#[derive(Debug, Clone)]
struct MessageDocument
{
    body: String,
    userId: String,
}

To construct a message using Convex's Value type, you need to create a BTreeMap<String, ConvexValue>:

use convex::Value as ConvexValue;
use std::collections::BTreeMap;

let create_message_args = BTreeMap::from([
    ("body".to_string(), ConvexValue::String("Crabs can walk in all directions, but mostly walk and run sideways".to_string())),
    ("userId".to_string(), ConvexValue::String("j97b03kebvey8gnqmdzhvwf69974e6c6".to_string())),
]);

client.mutation("createMessage", create_message_args).await?;

This BTreeMap represents a structured message that aligns with the MessageDocument schema, allowing you to pass it to Convex functions seamlessly.

Trade-offs

While both approaches can simplify initial development by eliminating the need to define and update Rust types manually, they come with significant trade-offs:

Loss of Type Safety: By using generic JSON or Convex's Value, you forfeit Rust's strong type guarantees. Errors related to data structure mismatches will only surface at runtime, rather than being caught at compile time.
Reduced Developer Experience: Without explicit types, you lose the benefits of Rust's powerful type system, such as autocomplete suggestions and compile-time checks. This can lead to a more error-prone and less efficient development process.

In summary, while the generic JSON approach and Convex's Value type can be quick fixes for avoiding manual type maintenance, they sacrifice the robustness and efficiency that Rust is known for. This underscores the need for a tool like convex-typegen, which can automatically generate Rust types that are perfectly in sync with your Convex backend, preserving both type safety and developer productivity.

Building convex-typegen

Embarking on the development of convex-typegen was a thrilling adventure that took me deep into the realms of Abstract Syntax Trees (ASTs) and the art of code generation. My mission was clear: to craft a tool that seamlessly converts Convex's JavaScript schema definitions into robust Rust types. This would not only enhance type safety but also liberate developers from the tedium of manual type maintenance. Here's a glimpse into how I brought this vision to life:

Step 1: Parsing JavaScript with Oxc

The first step in my journey was to parse the JavaScript schema definitions into a format that I could work with programmatically. This is where Abstract Syntax Trees (ASTs) come into play. An AST is a tree representation of the abstract syntactic structure of source code. Each node in the tree denotes a construct occurring in the source code.

To parse JavaScript into an AST, I used the Oxc JavaScript Oxidation Compiler. Oxc is a high-performance toolchain written in Rust, known for its speed and efficiency. Here's a simplified example of how I used it, inspired by the Oxc documentation:

use oxc::{
    allocator::Allocator,
    parser::{Parser, ParserReturn},
    span::SourceType,
};

let source_text = r#"
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  messages: defineTable({
    body: v.string(),
    userId: v.id("users"),
  }),
  users: defineTable({
    name: v.string(),
    tokenIdentifier: v.string(),
  }).index("by_token", ["tokenIdentifier"]),
});
"#;

// Memory arena where AST nodes are allocated.
let allocator = Allocator::default();
// Infer source type (TS/JS/ESM/JSX/etc) based on file extension
let source_type = SourceType::from_path("schema.js").unwrap();
let mut errors = Vec::new();

let parser_result = Parser::new(&allocator, source_text, source_type).parse();

// The program is the root of the AST.
let program = parser_result.program;

This AST provided a structured representation of the JavaScript code, which I could traverse and analyze to extract the necessary information for generating Rust types.

Step 2: Analyzing the AST

Once I had the AST, the next step was to analyze it to identify the schema definitions and their corresponding types. This involved traversing the AST and looking for specific patterns that matched Convex's schema definitions.

For example, I looked for defineSchema and defineTable calls and extracted the field names and types. This information was crucial for generating the corresponding Rust types.

fn find_define_schema(body: &[JsonValue]) -> Option<&JsonValue>
{
    for node in body {
        // Check if this is an export default declaration
        if let Some(declaration) = node.get("declaration") {
            // Check if this is a call expression
            if declaration["type"].as_str() == Some("CallExpression") {
                // Check if the callee is defineSchema
                if let Some(callee) = declaration.get("callee") {
                    if callee["type"].as_str() == Some("Identifier") && callee["name"].as_str() == Some("defineSchema") {
                        // Return the declaration node
                        return Some(declaration);
                    }
                }
            }
        }
    }
    None
}

Step 3: Constructing a Code Generator

With the AST parsed and analyzed, the next step was to save the schema and function information into Rust data types. This involved creating structured representations of the Convex schema, tables, columns, and functions.

use serde::Value as JsonValue;

/// The convex schema.
#[derive(Debug, Serialize, Deserialize)]
struct ConvexSchema
{
    tables: Vec<ConvexTable>,
}

/// A table in the convex schema.
#[derive(Debug, Serialize, Deserialize)]
struct ConvexTable
{
    name: String,
    columns: Vec<ConvexColumn>,
}

/// A column in the convex schema.
#[derive(Debug, Serialize, Deserialize)]
struct ConvexColumn
{
    name: String,
    data_type: JsonValue,
}

/// A list of all known convex functions.
type ConvexFunctions = Vec<ConvexFunction>;

/// Convex functions (Queries, Mutations, and Actions)
#[derive(Debug, Serialize, Deserialize)]
struct ConvexFunction
{
    name: String,
    params: Vec<ConvexFunctionParam>,
    type_: String,
    file_name: String,
}

/// A parameter in a convex function.
#[derive(Debug, Serialize, Deserialize)]
struct ConvexFunctionParam
{
    name: String,
    data_type: JsonValue,
}

These data structures allowed me to store information in a way that was organized and easy to manipulate. By serializing and deserializing these structures, I could seamlessly convert between the parsed AST and the Rust code I needed to generate.

Achieving Type Safety in Convex Functions

One key challenge was ensuring type safety in Convex functions. This required parsing the function arguments and generating corresponding Rust code that maintained type integrity. By analyzing the AST, I extracted function definitions, including their parameters and types, and mapped them to Rust's type system.

For each Convex function, I generated Rust code that defined the function's parameters and function query key, ensuring they matched the schema's expectations. This involved creating Rust structs and enums that mirrored the JavaScript types, providing compile-time guarantees of type safety.

Here's a conceptual example of how I approached this:

fn generate_function_code(function: ConvexFunction) -> String
{
    let mut code = String::new();

    // Generate the args struct name
    let struct_name = format!("{}Args", capitalize_first_letter(&function.name));

    // Generate struct with derive macros
    code.push_str("#[derive(Debug, Clone, Serialize, Deserialize)]\n");
    code.push_str(&format!("pub struct {} {{\n", struct_name));

    // Generate fields for each parameter
    for param in &function.params {
        let rust_type = convex_type_to_rust_type(&param.data_type, None, None);
        code.push_str(&format!("    pub {}: {},\n", param.name, rust_type));
    }

    code.push_str("}\n\n");

    // Add implementation block with static FUNCTION_PATH method
    code.push_str(&format!("impl {} {{\n", struct_name));
    code.push_str("    pub const FUNCTION_PATH: &'static str = ");
    code.push_str(&format!("\"{}:{}\";\n", function.file_name, function.name));
    code.push_str("}\n\n");

    // Generate From implementation to convert to BTreeMap
    code.push_str(&format!(
        "impl From<{}> for std::collections::BTreeMap<String, serde_json::Value> {{\n",
        struct_name
    ));
    code.push_str(&format!("    fn from(_args: {}) -> Self {{\n", struct_name));

    // Only create map and insert values if there are parameters
    if function.params.is_empty() {
        code.push_str("        std::collections::BTreeMap::new()\n");
    } else {
        code.push_str("        let mut map = std::collections::BTreeMap::new();\n");
        // Convert each field to a serde_json::Value and insert into map
        for param in &function.params {
            code.push_str(&format!(
                "        map.insert(\"{}\".to_string(), serde_json::to_value(_args.{}).unwrap());\n",
                param.name, param.name
            ));
        }
        code.push_str("        map\n");t6
    }

    code.push_str("    }\n");
    code.push_str("}\n\n");

    code
}

There are many more details to this process, but this gives you a good idea of how I approached it.

Putting it All Together

To start using convex-typegen, follow these steps:

Step 1: Setting Up `build.rs`

First, configure your build.rs file to generate types from your Convex schema. This setup ensures that your types are always up-to-date with any changes in your schema.

use std::path::PathBuf;
use convex_typegen::{generate, Configuration};

// Auto-rebuild the types if the schema or messages files change
println!("cargo:rerun-if-changed=convex/schema.ts");
println!("cargo:rerun-if-changed=convex/messages.ts");

let config = Configuration {
    // Tell the parser where to find the function definitions
    function_paths: vec![PathBuf::from("convex/messages.ts")],

    ..Default::default()
};

match generate(config) {
    Ok(_) => {}
    Err(e) => panic!("Typegen failed: {}", e),
};

This script leverages convex-typegen to parse your schema and generate corresponding Rust types, automatically rebuilding them whenever your schema changes. The default file generated is convex_types.rs, but you can change this in the output_file field of the Configuration struct. Make sure to add this file to your src/main.rs so cargo can find it.

Step 2: Writing Type-Safe Code

With the types generated, you can now write type-safe code that interacts with your Convex backend. Here's how you can perform the same message mutation with type safety:

use convex::ConvexClient;
use convex_typegen::convex::ConvexClientExt;

// Import the generated types
use convex_types::CreateMessageArgs;

let client = ConvexClient::new("your-convex-url").await?;

let message_args_map = client.prepare_args(CreateMessageArgs {
    body: "Crabs are omnivores, meaning they eat both plants and animals.".to_string(),
    userId: "j97b03kebvey8gnqmdzhvwf69974e6c6".to_string(),
});

let message_result = client.mutation(CreateMessageArgs::FUNCTION_PATH, message_args_map).await?;

In this version, CreateMessageArgs is a Rust struct generated by convex-typegen, ensuring the arguments you pass are type-checked at compile time. This not only prevents runtime errors but also enhances the developer experience with features like autocomplete and inline documentation. The FUNCTION_PATH constant is a string that points to the function you're calling, and it's generated by convex-typegen based on the function's location in your convex backend directory.

Closing Thoughts

Building convex-typegen was more than just solving a technical problem—it was an opportunity to embrace challenges, learn deeply, and reaffirm key principles of software development.

As developers, we often face scenarios where existing tools don't quite meet our needs. In these moments, the ability to create something new becomes crucial. Developing convex-typegen required not only a thorough understanding of Convex and Rust but also a willingness to innovate and tackle problems without a predefined path.

This project highlighted the critical role of type safety in modern software development. By ensuring type consistency across the backend and frontend, we can identify errors early, minimize runtime issues, and improve overall reliability. convex-typegen brings the robust type safety of TypeScript to the Rust ecosystem, providing compile-time guarantees that boost developer confidence.

Additionally, it underscores the transformative power of automation in streamlining workflows. Automating the generation of Rust types from Convex schemas saves time, reduces human error, and enables developers to focus on what truly matters—building features and solving complex problems. This focus not only enhances productivity but also leads to higher-quality software.

Ultimately, the journey of building convex-typegen reflects the importance of innovation, the power of type safety, the value of community collaboration, and the efficiency of automation. I hope this tool empowers other Rust developers to build more robust and reliable applications with ease.

Footnotes

GitHub Repository: View the source code and examples on GitHub.
YouTube Demo: Watch a demonstration of convex-typegen in action on YouTube.
Convex: Learn more about Convex and its capabilities on their official website.
Rust: Discover why Rust is a popular choice for backend development on the Rust official site.
Oxc JavaScript Oxidation Compiler: Explore the Oxc documentation for more details on parsing JavaScript with Rust.
serde_json: Check out the serde_json documentation for working with JSON in Rust.