expo-clerk-convex

This project implements an opinionated authentication architecture:

• Sign-in: Uses Clerk email/password authentication.
• Sign-up: Creates the account, triggers an email verification code, and completes verification within the app.
• Route Protection: Access to specific routes is controlled by the Clerk authentication state within the root Expo Router layout.
• Backend Security: Convex trusts the authenticated Clerk session for backend access. Note that this implementation does not mirror Clerk users into a separate Convex users table.

Follow these steps to clone the repository, install dependencies, and initialize the backend services.

1. Clone the repository:

git clone https://github.com/FlemingVincent/expo-clerk-convex.git
cd expo-clerk-convex

2. Install dependencies using bun:

bun install

3. Initialize the Convex backend:

npx convex dev

This command creates the convex/ directory, prompts for Convex sign-in, and provides the deployment URL required for the Expo app.

4. Start the Expo development server:

npx expo start --clear --reset-cache

Before setting up the local environment, you must configure your Clerk application to support the authentication flow used in this project:

1. Create a Clerk application at dashboard.clerk.com.
2. Enable email/password authentication.
3. Configure email verification to use an email code flow for sign-up.
4. Enable the Convex integration within the Clerk dashboard.
5. Locate your Clerk Frontend API URL; you will need this as the CLERK_JWT_ISSUER_DOMAIN for your Convex backend.

The project requires specific environment variables to link Clerk, Convex, and Expo.

Expo Environment Variables

Add these to your .env.local file:

• EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY: Your Clerk publishable key.
• EXPO_PUBLIC_CONVEX_URL: The deployment URL provided by npx convex dev.

Convex Environment Variables

Add this to your Convex dashboard environment variables:

• CLERK_JWT_ISSUER_DOMAIN: The Clerk Frontend API URL.

The project requires the EXPO_PUBLIC_CONVEX_URL environment variable to be defined in your .env file to initialize the Convex client. If this variable is missing, the application will throw an error: Add EXPO_PUBLIC_CONVEX_URL to your .env file.

EXPO_PUBLIC_CONVEX_URL=https://your-deployment-name.convex.cloud

To enable Clerk authentication within your Convex backend, you must define an AuthConfig object in convex/auth.config.ts. This configuration tells Convex which JWT issuer is authorized to authenticate requests.

Specifically, you must provide a providers array containing an object with:

• domain: The Clerk JWT issuer domain (e.g., https://your-issuer-domain.clerk.accounts.dev). This should be loaded from the CLERK_JWT_ISSUER_DOMAIN environment variable.
• applicationID: Set this to "convex" to match the expected application identifier for this integration.

import { AuthConfig } from "convex/server";

export default {
  providers: [
    {
      domain: process.env.CLERK_JWT_ISSUER_DOMAIN!,
      applicationID: "convex",
    },
  ],
} satisfies AuthConfig;

The application exports a pre-configured convex instance of ConvexReactClient. This instance is initialized using the EXPO_PUBLIC_CONVEX_URL and has unsavedChangesWarning set to false to prevent blocking UI interactions during development or usage.

import { convex } from './lib/convex';

// Use the exported convex instance to interact with your backend
// e.g., useQuery(api.myFunctions.myQuery, {});

Use query to define functions that read from your Convex database and are accessible from the client. The function receives a QueryCtx as its first argument.

import { query } from "./_generated/server";

export const myQuery = query({
  args: {},
  handler: async (ctx) => {
    // ctx is QueryCtx
    return await ctx.db.query("tableName").collect();
  },
});

Use httpAction to define functions that respond to incoming HTTP requests. These are used when you have routed a specific path and method in convex/http.js. The function receives an ActionCtx as its first argument and a Fetch API Request object as its second argument.

import { httpAction } from "./_generated/server";

export const myHttpAction = httpAction(async (ctx, request) => {
  // ctx is ActionCtx
  // request is a Fetch API Request object
  return new Response("Hello from HTTP!");
});

Use action to define functions that can execute arbitrary JavaScript code, including non-deterministic code or side-effects like calling third-party APIs. Actions cannot interact with the database directly; they must call queries or mutations using the ActionCtx. The function receives an ActionCtx as its first argument.

import { action } from "./_generated/server";

export const myAction = action({
  args: {},
  handler: async (ctx, args) => {
    // ctx is ActionCtx
    // Call a mutation to interact with the database
    await ctx.runMutation(api.myMutation, { text: "hello" });
  },
});