Integrating Convex with Expo (React Native)

Why this skill exists

Convex setup in React Native is straightforward, but small details (Expo environment variables, file locations, keeping convex dev running) regularly cause broken builds or “it returns undefined” confusion. This skill standardises a reliable, end-to-end workflow.

Non-negotiables (do these every time)

• Keep npx convex dev running while developing. It syncs functions + generates the convex/_generated API/types.
• Use Expo public env vars: the client should read process.env.EXPO_PUBLIC_CONVEX_URL.
• Create exactly one Convex client per app, and wrap the whole tree in ConvexProvider.
• React Native: set unsavedChangesWarning: false on ConvexReactClient (the default warning is web-centric).
• Don’t hand-type API names: always import from convex/_generated/api and call api.someFile.someExport.

First decision: what kind of Expo project is this?

1. expo-router project (common with create-expo-app):
   • root layout is usually app/_layout.tsx or src/app/_layout.tsx
2. classic App.tsx entrypoint:
   • wrap App.tsx with ConvexProvider

When unsure, search for expo-router in package.json and look for an app/ folder.

Workflow A — Add Convex to an existing Expo app (recommended default)

A1) Install Convex

From the Expo app root:

npx expo install convex

(If you aren’t using Expo’s installer, npm i convex also works.)

A2) Create a Convex dev deployment + backend folder

npx convex dev

What you should see / get:

• prompts to log in and create a project
• a new convex/ folder for backend functions
• .env.local containing EXPO_PUBLIC_CONVEX_URL=...
• the command keeps running to sync changes

A3) Ensure EXPO_PUBLIC_CONVEX_URL is available in development and builds

• Dev (Expo CLI / Metro): npx convex dev writes .env.local with EXPO_PUBLIC_CONVEX_URL.
• EAS builds: copy that value into EAS env vars.

See: references/eas-env.md

A4) Wire up the Convex client + provider (expo-router)

Edit app/_layout.tsx or src/app/_layout.tsx:

import { ConvexProvider, ConvexReactClient } from "convex/react";
import { Stack } from "expo-router";

const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL!, {
  unsavedChangesWarning: false,
});

export default function RootLayout() {
  return (
    <ConvexProvider client={convex}>
      <Stack />
    </ConvexProvider>
  );
}

If the project does not use expo-router

Wrap your top-level component (usually App.tsx) similarly:

import { ConvexProvider, ConvexReactClient } from "convex/react";

const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL!, {
  unsavedChangesWarning: false,
});

export default function App() {
  return (
    <ConvexProvider client={convex}>
      {/* your existing navigation / UI */}
    </ConvexProvider>
  );
}

A5) Create a first query + show it in the app

Use the canonical “tasks” example:

• backend: convex/tasks.ts
• seed: sampleData.jsonl
• import: npx convex import --table tasks sampleData.jsonl
• UI: useQuery(api.tasks.get)

See: references/tasks-example.md

✅ Quality gate: when the app loads, useQuery should initially be undefined (loading) and then become an array of tasks.

Workflow B — Add a new feature end-to-end (schema → function → UI)

Use this loop for each feature (it keeps you “in sync” across app/backend/db):

1. Data model first (schema + indexes)

   • define/extend tables in convex/schema.ts
   • add indexes you’ll query by (before you have 1000+ docs)
   • see: references/schema-and-indexes.md

2. Backend API (query/mutation/action)

   • prefer query for reads, mutation for writes, action when you need Node APIs or third-party fetches that don’t fit the normal runtime
   • always validate args with v.*
   • see: references/functions.md

3. Frontend integration

   • useQuery(api.file.export)
   • useMutation(api.file.export)
   • consider loading/empty/error states explicitly
   • see: references/frontend-patterns.md

4. Run/verify

   • keep npx convex dev running
   • restart Metro if env vars changed
   • run the validation script: python scripts/validate_project.py

Workflow C — Authentication (pick one and stick to it)

Convex supports multiple approaches; the right choice depends on your app’s needs:

• Convex Auth: simplest end-to-end if you’re all-in on Convex.
• Clerk: common in Expo; Convex provides <ConvexProviderWithClerk> for integration.
• Other OIDC/JWT providers: generally work by passing JWTs and enforcing access control in functions.

See: references/auth.md

Workflow D — File uploads from Expo / React Native

Use Convex File Storage upload URLs:

1. mutation generates a short-lived upload URL
2. client fetch(putUrl, { method: "POST", ... })
3. store the returned storageId in your table

See: references/file-uploads.md

Troubleshooting (fast path)

If something breaks, do this in order:

1. Is npx convex dev running? If not, start it.
2. Is process.env.EXPO_PUBLIC_CONVEX_URL defined at runtime?
   • if you added/changed .env*, restart Metro with cache cleared.
3. Does the app wrap the entire tree with ConvexProvider?
4. Are you importing api from convex/_generated/api and calling useQuery(api.x.y)?
5. Run: python scripts/validate_project.py

More cases + fixes: references/troubleshooting.md

Scripts included

• scripts/validate_project.py — checks package.json, env vars, Convex folder, and provider wiring.
• scripts/scaffold_tasks_example.py — generates the “tasks” example files (dry-run by default).

References (load only when needed)

• references/eas-env.md — .env.local vs EAS env vars, Expo gotchas
• references/tasks-example.md — seed + query + UI in Expo
• references/schema-and-indexes.md — schemas, validators, indexes, query perf
• references/functions.md — queries, mutations, actions patterns
• references/frontend-patterns.md — hooks patterns, loading/error handling, navigation
• references/auth.md — Convex Auth vs Clerk vs others, access control patterns
• references/file-uploads.md — RN/Expo file URIs → Blob → Convex storage
• references/troubleshooting.md — common issues and exact fixes
• references/sources.md — upstream docs used to build this skill