Integrating Convex Expo

Integrating Convex with Expo (React Native)

Use this skill to add, repair, extend, or harden a Convex backend for an Expo app without drifting into web-only patterns or generic React Native advice.

Use this skill for

• Adding Convex to an existing Expo or Expo Router app.
• Fixing broken environment setup, provider wiring, or generated API imports.
• Building an end-to-end feature slice: schema, indexes, backend functions, frontend hooks, and validation.
• Choosing and implementing auth for Expo + Convex.
• Uploading files from Expo URIs into Convex storage.
• Refactoring for pagination, indexes, migrations, or reusable components.
• Hardening a project before preview or production release.

Do not use this skill for

• Pure Expo UI, animation, navigation, or styling work with no Convex involvement.
• Convex projects whose frontend is not Expo or React Native.
• Generic backend architecture discussions that do not need Expo-specific environment or client wiring.

Success criteria

A good outcome should leave the project with:

1. A single, correctly scoped Convex client and provider. 2. Working EXPO_PUBLIC_CONVEX_URL handling in local development and EAS. 3. Backend functions that match Convex best practices for validators, auth, actions, and query performance. 4. Frontend hooks using generated api references with clear loading, empty, and error states. 5. A validation pass using scripts/validate_project.py. 6. A clear path for future growth: pagination, indexes, auth wrappers, migrations, and linting.

Non-negotiables

• Keep npx convex dev running while developing or repairing the integration.
• Read the deployment URL from process.env.EXPO_PUBLIC_CONVEX_URL.
• Mirror that value into EAS environments for preview and production builds.
• Create exactly one ConvexReactClient per app, outside render paths.
• Mount the provider at the true root: app/_layout.tsx, src/app/_layout.tsx, or App.tsx.
• In Expo and React Native, set unsavedChangesWarning: false.
• Import generated references from convex/_generated/api rather than stringly typed names.
• Treat all client-callable Convex functions as untrusted entry points.
• Add args validators to public functions, and prefer returns validators as well.
• Keep public wrappers thin; move repeated logic into helpers, internal functions, or custom wrappers.
• Do not use Date.now() or new Date() inside query logic.
• Do not use Node-only APIs or third-party SDKs inside queries or mutations.
• Put external API calls, heavy compute, or Node-only libraries in action or internalAction files; if a file starts with "use node", keep it action-only.
• Avoid .filter() and unbounded .collect() on large tables; prefer indexes plus pagination.
• Await every promise.
• Prefer TypeScript strict mode and the official Convex ESLint plugin.

First-pass triage

Before making changes, inspect the project and classify the job.

1. Identify the app entrypoint

Check for:

• app/_layout.tsx or src/app/_layout.tsx for Expo Router.
• App.tsx or App.jsx for classic entrypoints.

2. Audit Convex state

Look for:

• package.json dependencies: convex, expo, auth libraries, ESLint tooling.
• convex/ and convex/_generated/.
• .env.local, .env, .env.development, .env.production.
• eas.json if cloud builds matter.
• Existing provider usage: ConvexProvider, ConvexProviderWithClerk, or custom auth wrappers.
• Existing schema and indexes in convex/schema.ts.
• Existing public functions with missing validators, auth checks, or pagination.

3. Run the validator

From the project root:

python scripts/validate_project.py --root <project-root>

Use --json for machine-readable output or --fail-on-warning when you want stricter gating.

4. Choose the workflow

• Bootstrap / repair baseline: missing Convex setup, env vars, provider, or generated API.
• Build a feature slice: add backend data and UI together.
• Auth: add or repair sign-in and backend authorization.
• File uploads: move media or documents from device URIs into Convex storage.
• Scale / harden: indexes, pagination, components, linting, production checklist.
• Migration: reshape existing tables or gradually move from another backend.

Workflow A — Bootstrap or repair the baseline integration

Step 1: Install or confirm the client package

npx expo install convex

Step 2: Create or reconnect the Convex project

npx convex dev

Expect this to:

• create or connect a Convex project,
• create convex/ if missing,
• generate convex/_generated/,
• write EXPO_PUBLIC_CONVEX_URL to .env.local,
• and keep syncing while the command runs.

Step 3: Ensure the root provider exists

For Expo Router:

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>
  );
}

For classic App.tsx, wrap the top-level navigation tree the same way.

Step 4: Confirm generated imports

Use:

import { api } from "../convex/_generated/api";

or the correct relative path for the project layout. Do not hand-write function names.

Step 5: Verify development and build environments

Read references/eas-env.md and ensure the same deployment URL policy is reflected in EAS.

Step 6: Validate and smoke-test

• Start the Expo app.
• Confirm useQuery(...) moves from undefined to real data.
• Run python scripts/validate_project.py --root <project-root>.
• If needed, scaffold the canonical example with python scripts/scaffold_tasks_example.py --root <project-root>.

Workflow B — Build a feature slice end to end

Build each feature in the order below.

1. Model the access pattern first

Before touching code, answer:

• Is the data public, user-scoped, org-scoped, or admin-only?
• Will the list stay small, or should it paginate?
• Which fields are lookup keys and therefore need indexes?
• Does any step require an external API, AI SDK, Stripe, or Node API?

2. Design the schema

Add or extend convex/schema.ts before the function layer whenever the model is stabilising.

Use references/schema-and-indexes.md for:

• flat relational modelling,
• foreign-key indexing,
• compound indexes around actual query shapes,
• bounded array guidance,
• and pagination thresholds.

3. Implement backend functions

Use references/functions.md for the detailed patterns.

Default rules:

• query for deterministic reads.
• mutation for writes.
• action or internalAction for external APIs, third-party SDKs, or Node-only code.
• internalQuery or internalMutation for logic that should never be callable from the client.

4. Enforce access on the backend

If the feature is not public, do one of these:

• explicit ctx.auth.getUserIdentity() checks in each function, or
• reusable custom wrappers via convex-helpers.

See references/auth.md and references/components-and-helpers.md.

5. Wire the frontend

Use references/frontend-patterns.md.

Always handle:

• loading: useQuery(...) === undefined,
• empty state,
• mutation pending state where relevant,
• recoverable errors,
• and pagination for unbounded lists.

6. Validate the slice

Before finishing:

• run the validator with the project root,
• run lint and typecheck if the project has them,
• verify the feature on device or simulator,
• and update or add indexes before shipping.

Workflow C — Authentication and authorization

Pick one auth story and keep the stack coherent.

Option 1: Clerk

Good when the app already uses Clerk or wants a polished auth product.

Option 2: Convex Auth

Good when you want a Convex-native auth stack and are comfortable adopting a beta library.

Option 3: Existing JWT or OIDC provider

Good when the product already depends on Auth0, WorkOS, a company IdP, or another OIDC flow.

Rules regardless of provider

• Backend authorization is mandatory; client-side gating is only for UX.
• If you persist users in Convex, index by a stable identifier such as tokenIdentifier.
• Check ownership, organisation membership, or role on every protected function.
• Prefer helper functions or custom wrappers instead of repeating auth boilerplate.
• Use internal functions for privileged internal-only operations.

Read references/auth.md for a decision matrix and implementation patterns.

Workflow D — File uploads from Expo

Use Convex upload URLs rather than trying to push raw files through a mutation.

Recommended flow:

1. public or protected mutation returns ctx.storage.generateUploadUrl(), 2. client loads the local file:// URI with fetch(uri) and converts it to a Blob, 3. client POSTs the blob to the upload URL, 4. second mutation stores the returned storageId plus app-specific metadata, 5. optional scheduled or action-based post-processing happens afterwards.

Read references/file-uploads.md.

Workflow E — Scale and harden

Once the baseline works, raise the quality bar.

Performance

• Replace .filter() scans with indexed queries where possible.
• Replace unbounded .collect() with take, first, or paginated queries.
• Use usePaginatedQuery for growing feeds, notifications, and infinite-scroll screens.
• Push repeated or reusable feature areas into Convex components when boundaries are clear.

Safety

• Add validators consistently.
• Keep privileged logic behind internal functions.
• Use ConvexError or clear return shapes for expected failures.
• Never trust IDs from the client without checking ownership or membership.

Maintainability

• Turn on @convex-dev/eslint-plugin.
• Use TypeScript strict mode.
• Keep wrappers thin and move shared logic into plain TypeScript helpers.
• Separate "use node" action files from regular runtime files.

Read references/production-checklist.md.

Workflow F — Migrations

When changing a live schema, prefer additive transitions.

Default migration strategy:

1. add new fields or tables in a backwards-compatible way, 2. dual-read or dual-write if the shape is changing, 3. backfill existing documents in idempotent batches, 4. switch readers and writers, 5. then remove the old shape.

Use internal functions or scheduled jobs for backfills, and keep migrations restart-safe.

Read references/migrations.md.

Fast troubleshooting path

If the app is broken, check these in order:

1. Is npx convex dev running and free of TypeScript errors? 2. Does .env.local contain EXPO_PUBLIC_CONVEX_URL? 3. Was Metro restarted after the env file changed? 4. Is there exactly one ConvexReactClient? 5. Is the provider mounted at the real root? 6. Does convex/_generated/api exist, and are imports pointing at it correctly? 7. Are public functions missing args or returns validators? 8. Is a query using Date.now(), .filter(), or unbounded .collect()? 9. Is a "use node" file incorrectly mixing queries or mutations? 10. Is auth mismatched between the client provider and the backend config?

See references/troubleshooting.md.

Available scripts

• scripts/validate_project.py
• Validates the project rooted at --root or, if copied into a repo, the current working tree.
• Validates Expo and Convex dependencies.
• Checks env files, provider wiring, generated code, validator presence, "use node" misuse, and common query anti-patterns.
• Supports --json, --root, and --fail-on-warning.

• scripts/scaffold_tasks_example.py
• Dry-run by default.
• Can generate sampleData.jsonl, convex/schema.ts, convex/tasks.ts, and an optional Expo screen file.
• Supports --write, --overwrite, --ui-file, and --json.

References

Load only the file that matches the current task.

• references/eas-env.md — local envs, EAS envs, and deployment URL handling.
• references/tasks-example.md — canonical minimal example for the stack.
• references/schema-and-indexes.md — schema design, indexes, query shape mapping, and pagination triggers.
• references/functions.md — query, mutation, action, internal function, validators, and runtime boundaries.
• references/frontend-patterns.md — provider placement, hook usage, loading and error states, and paginated lists.
• references/auth.md — Clerk, Convex Auth, JWT or OIDC, user mapping, and server-side authorization.
• references/file-uploads.md — upload URLs, Expo URI handling, metadata storage, and post-processing.
• references/components-and-helpers.md — Convex components and convex-helpers patterns.
• references/migrations.md — additive rollout, backfills, dual reads and writes, and batched migrations.
• references/production-checklist.md — pre-release hardening checklist.
• references/troubleshooting.md — common failures and exact fixes.
• references/evaluation.md — how to use the bundled trigger and output eval files.
• references/sources.md — upstream docs and materials used for this rewrite.

Authentication and authorization for Expo + Convex

This reference is about choosing an auth stack and then enforcing access correctly on the backend.

First principle

Authentication answers who the user is.

Authorization answers what that user may do.

Expo screens can help with auth UX, but authorization must live in Convex functions.

Decision matrix

Choose Clerk when

• the app already uses Clerk,
• you want polished hosted auth flows,
• you want a familiar Expo-friendly product auth layer,
• or the team already knows Clerk.

Choose Convex Auth when

• you want a Convex-native auth stack,
• you do not want a separate auth SaaS for this project,
• and you are comfortable adopting a beta library.

Choose an existing JWT or OIDC provider when

• the company already uses Auth0, WorkOS, an enterprise IdP, or a custom OIDC flow,
• the app needs to plug into an existing identity estate,
• or migrations would be more expensive than keeping the current provider.

Backend rules that never change

• Never rely on a client-provided userId without verifying it.
• Every protected function should derive the current user from ctx.auth.getUserIdentity(), directly or via a wrapper.
• Check ownership, membership, or role before returning data or performing writes.
• Use internal functions for privileged operations that should not be directly public.

Users table pattern

If the product needs user profiles in Convex, create a users table keyed by a stable identity field.

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

export default defineSchema({
  users: defineTable({
    tokenIdentifier: v.string(),
    email: v.string(),
    name: v.string(),
    imageUrl: v.optional(v.string()),
    role: v.union(v.literal("user"), v.literal("admin")),
  })
    .index("by_token", ["tokenIdentifier"])
    .index("by_email", ["email"]),
});

Identity lookup helper

import type { MutationCtx, QueryCtx } from "./_generated/server";

export async function getCurrentUser(ctx: QueryCtx | MutationCtx) {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) {
    throw new Error("Not authenticated");
  }

  const user = await ctx.db
    .query("users")
    .withIndex("by_token", (q) =>
      q.eq("tokenIdentifier", identity.tokenIdentifier),
    )
    .unique();

  if (!user) {
    throw new Error("User not found");
  }

  return user;
}

Clerk notes

Typical stack:

• @clerk/clerk-expo on the client,
• Convex configured with Clerk as an auth provider,
• a root provider that combines Clerk and Convex,
• backend functions that still perform access checks.

Patterns to remember:

• UI can be gated with Clerk state and Convex auth helpers.
• Convex should still validate the token and enforce access on reads and writes.
• If the app stores user documents, sync them from a protected mutation rather than trusting client state.

Convex Auth notes

Use this when you want auth directly in the Convex backend.

What to watch:

• it supports React Native,
• but it is still beta,
• so check current docs before making it the default for a production-critical app.

For teams already committed to a separate identity provider, Convex Auth may not be the cheapest migration.

Generic JWT or OIDC notes

When keeping an existing provider:

• configure Convex to validate the provider’s JWTs,
• ensure the token contains a stable subject or identifier,
• map that identifier to the users table when needed,
• keep the backend checks exactly as strict as with any other provider.

Custom function wrappers with convex-helpers

If many functions repeat the same auth and tenant checks, use wrappers.

Example: authenticated query wrapper

import { customQuery, customMutation } from "convex-helpers/server/customFunctions";
import { query, mutation } from "../_generated/server";
import { getCurrentUser } from "./auth";

export const authedQuery = customQuery(query, {
  args: {},
  input: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    return { ctx: { ...ctx, user }, args };
  },
});

export const authedMutation = customMutation(mutation, {
  args: {},
  input: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    return { ctx: { ...ctx, user }, args };
  },
});

Example: org-scoped wrapper

import { customQuery } from "convex-helpers/server/customFunctions";
import { query } from "../_generated/server";
import { v } from "convex/values";
import { getCurrentUser } from "./auth";

export const orgQuery = customQuery(query, {
  args: {
    organizationId: v.id("organizations"),
  },
  input: async (ctx, args) => {
    const user = await getCurrentUser(ctx);

    const membership = await ctx.db
      .query("organizationMembers")
      .withIndex("by_org_and_user", (q) =>
        q.eq("organizationId", args.organizationId).eq("userId", user._id),
      )
      .unique();

    if (!membership) {
      throw new Error("Not authorized for this organization");
    }

    return {
      ctx: {
        ...ctx,
        user,
        organizationId: args.organizationId,
        role: membership.role,
      },
      args,
    };
  },
});

Backend authorization patterns

Owner-only resource

• verify the current user,
• fetch the resource,
• compare resource.userId with user._id,
• reject mismatches.

Team or org membership

• store membership rows in a join table,
• index by (organizationId, userId) or (teamId, userId),
• check membership before loading or mutating resources.

Role-based admin access

• keep a role field on the user or membership row,
• centralise the check in a helper or wrapper,
• and avoid copying role logic across dozens of files.

Common mistakes

UI says signed in but Convex behaves unauthenticated

Usually caused by one of these:

• the root provider pairing is incomplete,
• the backend provider config does not match the client provider,
• or the client is rendering too early before Convex auth has finished initialising.

Resource access keyed by email alone

Do not use mutable or user-controlled fields like email as the only access key. Resolve the verified identity first.

Repeating auth logic everywhere

If the same auth and tenant boilerplate appears in three or more places, wrap it.

Review checklist

• [ ] Auth provider choice matches the project’s existing stack.
• [ ] Protected functions derive identity from Convex auth, not from the client alone.
• [ ] A stable identity field such as tokenIdentifier is indexed.
• [ ] Ownership or membership checks are implemented on the backend.
• [ ] Repeated auth boilerplate is centralised in helpers or wrappers.
• [ ] Privileged workflows are moved behind internal functions when appropriate.

Convex components and convex-helpers

Use this reference when the backend is starting to sprawl or when repeated patterns deserve their own abstraction.

When to use convex-helpers

Install convex-helpers when you want proven patterns for:

• auth wrappers,
• tenant wrappers,
• relationship helpers,
• sessions,
• and other common building blocks.

npm install convex-helpers

Highest-value helper: custom function wrappers

This is the most useful pattern for Expo apps with authenticated user data.

Why wrap functions?

Without wrappers, every query and mutation repeats:

• identity lookup,
• user lookup,
• membership checks,
• and role checks.

That repetition is noisy and easy to get wrong.

Authenticated wrapper example

convex/lib/authFunctions.ts

import { customQuery, customMutation } from "convex-helpers/server/customFunctions";
import { query, mutation } from "../_generated/server";
import { getCurrentUser } from "./auth";

export const authedQuery = customQuery(query, {
  args: {},
  input: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    return { ctx: { ...ctx, user }, args };
  },
});

export const authedMutation = customMutation(mutation, {
  args: {},
  input: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    return { ctx: { ...ctx, user }, args };
  },
});

Use it like this:

import { authedQuery, authedMutation } from "./lib/authFunctions";
import { v } from "convex/values";

export const listMine = authedQuery({
  args: {},
  handler: async (ctx) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", ctx.user._id))
      .order("desc")
      .take(50);
  },
});

export const create = authedMutation({
  args: { title: v.string() },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", {
      userId: ctx.user._id,
      title: args.title.trim(),
      createdAt: Date.now(),
    });
  },
});

Tenant-scoped wrapper

When the product has organisations or teams, wrap membership checks too.

Benefits:

• less boilerplate,
• fewer authorization mistakes,
• cleaner function bodies,
• and better consistency across the backend.

Relationship helpers

If the backend frequently loads related entities, relationship helpers can keep code readable.

Typical examples:

• load task + assignee,
• load project + members,
• load channel + unread counts,
• load file + owner.

Use them when they make the code clearer, but still design indexes properly first.

When to use Convex components

Convex components are best when a feature area wants a strong internal boundary.

Good candidates:

• rate limiting,
• notifications,
• file handling,
• billing,
• analytics,
• reusable auth or organisation infrastructure.

Use a component when the feature has:

• its own tables,
• its own functions,
• a reusable or swappable boundary,
• or enough complexity that it muddies the rest of the app.

Do not reach for components too early

For a small Expo app, plain convex/*.ts modules are simpler. Introduce components when they actually reduce complexity.

Practical decision rule

Stay with plain modules when

• the feature is local to one app,
• it has only a few functions,
• and the boundary is still evolving quickly.

Move toward components when

• the feature is reused across domains,
• multiple modules depend on it,
• you want clearer ownership and isolation,
• or a third-party official component already solves the problem well.

Example: file handling boundary

A growing file feature often wants:

• upload metadata tables,
• processing actions,
• thumbnail logic,
• permissions,
• and serving helpers.

That is a good place to consider a component or at least a dedicated domain subtree.

Review checklist

• [ ] Repeated auth logic has been centralised if it appears often.
• [ ] Wrappers still keep authorization decisions explicit and understandable.
• [ ] Relationships are backed by indexes before helper abstractions are added.
• [ ] Components are introduced to reduce complexity, not for novelty.
• [ ] The backend remains easy to navigate for someone new to the codebase.

Expo environment handling for Convex

Core rule

The Expo client should read the Convex deployment URL from:

process.env.EXPO_PUBLIC_CONVEX_URL

Anything else causes avoidable breakage.

What npx convex dev is expected to do

Running:

npx convex dev

should:

• create or connect a Convex project,
• create the convex/ backend directory if it does not exist,
• keep a sync process running,
• and write the current deployment URL into .env.local as EXPO_PUBLIC_CONVEX_URL=....

Treat .env.local as the local-development source of truth.

Recommended deployment URL policy

Use separate Convex deployments for each environment whenever the product has meaningful preview and production stages.

• development: the local or shared dev deployment used by npx convex dev
• preview: a preview deployment used by EAS preview builds
• production: the production Convex deployment used by store releases

Do not casually point preview or production builds at a development deployment.

Local development checklist

1. Run npx convex dev. 2. Confirm .env.local exists. 3. Confirm it contains:

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

4. Restart Metro if the value was added or changed after the dev server started. 5. If using multiple local .env* files, make sure they do not override or shadow the value unintentionally.

EAS builds

EAS cloud builds do not read your local .env.local file. Copy the value into EAS environment variables.

Example:

eas env:create   --name EXPO_PUBLIC_CONVEX_URL   --value https://YOUR_DEPLOYMENT_URL.convex.cloud   --visibility plaintext   --environment development   --environment preview   --environment production

Replace the value with the deployment URL from the correct Convex environment.

Safer operational pattern

When you create or rotate a deployment URL:

1. update the local .env.local, 2. update the EAS environment value for the matching build environments, 3. rebuild any preview or production apps that should pick up the new value, 4. verify the app points to the intended Convex deployment.

Provider snippet

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>
  );
}

Common failure modes

process.env.EXPO_PUBLIC_CONVEX_URL is undefined

Likely causes:

• npx convex dev has never been run in this project.
• .env.local was not created where Expo expects it.
• Metro was not restarted after the env file changed.
• The code uses CONVEX_URL or another variable name without the EXPO_PUBLIC_ prefix.

Local development works but EAS build fails

Likely causes:

• the value exists only in .env.local,
• preview or production EAS environments were not updated,
• or the wrong deployment URL was copied into EAS.

Preview build is hitting production data

Likely causes:

• preview and production share the same EXPO_PUBLIC_CONVEX_URL,
• or the build profile uses the wrong EAS environment.

Validation tips

• Run python scripts/validate_project.py.
• Grep the repo for EXPO_PUBLIC_CONVEX_URL.
• Keep a short note in the repository or internal docs describing which Convex deployment maps to each build profile.

Evaluating this skill

This skill bundles two evaluation aids:

• evals/trigger-queries.json
• evals/evals.json

Use them to test both when the skill triggers and whether it produces good outputs once loaded.

1. Trigger evaluation

evals/trigger-queries.json contains realistic prompts labelled with should_trigger: true or false.

How to use it

• Run each query several times rather than only once.
• Record whether the skill loads.
• Calculate a trigger rate for each query.
• Tighten the description if true cases fail to trigger.
• Add scope or negative guidance if false cases trigger too often.

What good trigger tests look like

A useful set includes:

• obvious should-trigger requests,
• paraphrases and typo-heavy variants,
• and near-miss should-not-trigger requests such as generic Expo UI work or non-Expo Convex tasks.

2. Functional evaluation

evals/evals.json contains higher-level tasks with an expected outcome description.

Each case is designed to answer:

• does the skill pick the right workflow,
• does it produce the right edits or guidance,
• does it avoid common Convex mistakes,
• and does it improve results compared with no skill?

Recommended evaluation loop

With the skill

Run each eval with this skill available.

Without the skill

Run the same eval in a clean session without the skill, or against the previous skill version.

Compare

Look at:

• correctness,
• completeness,
• tool choice,
• number of avoidable follow-up questions,
• and whether the output follows Convex best practices.

What to grade in this skill specifically

• correct Expo entrypoint detection,
• correct use of EXPO_PUBLIC_CONVEX_URL,
• correct root provider wiring,
• generated API usage,
• validators on public Convex functions,
• auth enforced on the backend,
• correct action vs mutation boundaries,
• pagination for growing lists,
• and migration safety when schema changes are involved.

Suggested lightweight rubric

For each functional eval, score:

• Pass: the output is correct and production-safe.
• Borderline: the main idea is right but it misses one important hardening step.
• Fail: it uses the wrong workflow or introduces unsafe patterns.

Iteration advice

If the skill under-triggers:

• add clearer user-intent phrases to the frontmatter description,
• include more Expo-specific language,
• and add near-obvious trigger phrases such as expo-router, EXPO_PUBLIC_CONVEX_URL, useQuery undefined, Clerk, or file:// uploads.

If it over-triggers:

• narrow the description,
• add “do not use” scope language,
• and add more near-miss negatives to the trigger file.

If it loads correctly but outputs weak advice:

• strengthen the body instructions,
• move specifics into references,
• and expand the functional eval set around the weak scenario.

File uploads from Expo to Convex storage

Expo gives you local file:// URIs from packages such as:

• expo-image-picker
• expo-document-picker
• expo-av
• custom camera or recorder flows

The most reliable Convex pattern is:

1. request an upload URL from a mutation, 2. load the local URI with fetch(uri), 3. convert it to a Blob, 4. POST the blob to the upload URL, 5. store the returned storageId plus your own metadata in a second mutation.

Why use upload URLs?

Benefits:

• avoids squeezing file bytes through normal function arguments,
• works well for mobile file sources,
• separates transport from your domain metadata,
• and lets you attach later processing steps cleanly.

Schema example

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

export default defineSchema({
  files: defineTable({
    ownerId: v.id("users"),
    storageId: v.id("_storage"),
    originalName: v.string(),
    mimeType: v.string(),
    sizeBytes: v.optional(v.number()),
    kind: v.union(
      v.literal("image"),
      v.literal("document"),
      v.literal("audio"),
      v.literal("other"),
    ),
    createdAt: v.number(),
  })
    .index("by_owner", ["ownerId"])
    .index("by_storage", ["storageId"]),
});

Backend functions

convex/files.ts

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

export const generateUploadUrl = mutation({
  args: {},
  returns: v.string(),
  handler: async (ctx) => {
    // Add auth checks here if uploads are protected.
    return await ctx.storage.generateUploadUrl();
  },
});

export const saveUploadedFile = mutation({
  args: {
    ownerId: v.id("users"),
    storageId: v.id("_storage"),
    originalName: v.string(),
    mimeType: v.string(),
    sizeBytes: v.optional(v.number()),
    kind: v.union(
      v.literal("image"),
      v.literal("document"),
      v.literal("audio"),
      v.literal("other"),
    ),
  },
  returns: v.id("files"),
  handler: async (ctx, args) => {
    return await ctx.db.insert("files", {
      ownerId: args.ownerId,
      storageId: args.storageId,
      originalName: args.originalName,
      mimeType: args.mimeType,
      sizeBytes: args.sizeBytes,
      kind: args.kind,
      createdAt: Date.now(),
    });
  },
});

export const getFileMetadata = query({
  args: {
    fileId: v.id("files"),
  },
  returns: v.union(
    v.object({
      _id: v.id("files"),
      _creationTime: v.number(),
      ownerId: v.id("users"),
      storageId: v.id("_storage"),
      originalName: v.string(),
      mimeType: v.string(),
      sizeBytes: v.optional(v.number()),
      kind: v.union(
        v.literal("image"),
        v.literal("document"),
        v.literal("audio"),
        v.literal("other"),
      ),
      createdAt: v.number(),
    }),
    v.null(),
  ),
  handler: async (ctx, args) => {
    return await ctx.db.get(args.fileId);
  },
});

If uploads are protected

Do not accept ownerId blindly from the client in a real app. Resolve the current user from auth and write that verified owner ID instead.

Expo client example

import { api } from "../convex/_generated/api";
import { useMutation } from "convex/react";

const generateUploadUrl = useMutation(api.files.generateUploadUrl);
const saveUploadedFile = useMutation(api.files.saveUploadedFile);

export async function uploadFromUri(params: {
  uri: string;
  ownerId: string;
  originalName: string;
  mimeType: string;
  sizeBytes?: number;
  kind: "image" | "document" | "audio" | "other";
}) {
  const postUrl = await generateUploadUrl();

  const fileResponse = await fetch(params.uri);
  if (!fileResponse.ok) {
    throw new Error("Failed to read the local file URI");
  }

  const blob = await fileResponse.blob();

  const uploadResponse = await fetch(postUrl, {
    method: "POST",
    headers: {
      "Content-Type": params.mimeType,
    },
    body: blob,
  });

  if (!uploadResponse.ok) {
    throw new Error("Failed to upload file bytes to Convex");
  }

  const { storageId } = await uploadResponse.json();

  return await saveUploadedFile({
    ownerId: params.ownerId,
    storageId,
    originalName: params.originalName,
    mimeType: params.mimeType,
    sizeBytes: params.sizeBytes,
    kind: params.kind,
  });
}

Optional post-processing

Common follow-up jobs:

• image resizing,
• audio transcription,
• virus scanning,
• metadata extraction,
• PDF text extraction,
• thumbnail creation.

Good pattern:

1. the metadata mutation inserts the file record, 2. it schedules or triggers an internal action, 3. the action calls the external service or heavy processor, 4. an internal mutation stores the result.

Serving files back to the app

Typical options:

• store the storageId and request a serving URL when needed,
• or return URLs from a query alongside your domain metadata.

Keep privacy in mind. If the file is protected, do not hand out URLs in a query that lacks authorization checks.

Gotchas

Wrong MIME type

Mobile uploads often fail quietly or behave strangely when the Content-Type header is missing or incorrect.

Upload succeeds but metadata is missing

This usually means the second mutation failed or was never awaited.

Metadata saved but post-processing never ran

Check:

• scheduler calls are awaited,
• the scheduled function is internal and callable,
• and the action file is in the correct runtime if it uses Node-only packages.

Huge feeds of uploaded assets

Do not .collect() every file document. Paginate user libraries and media lists.

Review checklist

• [ ] Upload URL comes from a mutation.
• [ ] Local URI is converted to a Blob before upload.
• [ ] The upload fetch call sets the correct Content-Type.
• [ ] The returned storageId is persisted with domain metadata.
• [ ] Protected uploads derive ownership from auth on the backend.
• [ ] Follow-up processing happens in actions or internal functions.
• [ ] Large media libraries use pagination.

Frontend patterns for Expo + Convex

Use this reference when wiring the Convex client into an Expo app and when connecting screens to backend functions.

Root provider placement

Expo Router

Mount the provider in 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>
  );
}

Classic App.tsx

Wrap the navigation container or root screen tree in the same provider.

One client only

Create the client once at module scope.

Bad:

export default function App() {
  const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL!);
  return <ConvexProvider client={convex}>{/* ... */}</ConvexProvider>;
}

Why it is bad:

• recreates the client on render,
• breaks subscriptions,
• makes debugging confusing.

useQuery lifecycle

useQuery(...) behaves like this:

• undefined during the initial load,
• a real value once the query returns,
• reactive updates afterwards.

Always handle the loading phase explicitly.

const project = useQuery(api.projects.byId, { projectId });

if (project === undefined) {
  return <ActivityIndicator />;
}

useMutation

Mutations return a callable function.

const createTask = useMutation(api.tasks.create);

await createTask({
  projectId,
  title: "Draft landing page",
});

Tips:

• trim user input before sending,
• disable repeated taps while a mutation is in flight when needed,
• rely on reactivity instead of manually refetching whenever possible.

useAction

Use when the backend function is an action.

Typical cases:

• AI or summarisation,
• export or import jobs,
• external service calls,
• Stripe, email, or webhook tooling.

const runSummary = useAction(api.aiActions.generateAndStoreSummary);
await runSummary({ noteId });

Paginated lists

For feeds, inboxes, chat history, or large tables, pair a paginated query with usePaginatedQuery.

import { usePaginatedQuery } from "convex/react";

const { results, status, loadMore } = usePaginatedQuery(
  api.notifications.listMine,
  {},
  { initialNumItems: 20 },
);

Expo / React Native list pattern

import { ActivityIndicator, FlatList, Pressable, Text, View } from "react-native";

export function NotificationsScreen() {
  const { results, status, loadMore } = usePaginatedQuery(
    api.notifications.listMine,
    {},
    { initialNumItems: 20 },
  );

  const isInitialLoading = results.length === 0 && status === "LoadingFirstPage";

  if (isInitialLoading) {
    return (
      <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
        <ActivityIndicator />
      </View>
    );
  }

  return (
    <FlatList
      data={results}
      keyExtractor={(item) => item._id}
      renderItem={({ item }) => <Text>{item.title}</Text>}
      onEndReached={() => {
        if (status === "CanLoadMore") {
          loadMore(20);
        }
      }}
      onEndReachedThreshold={0.6}
      ListFooterComponent={
        status === "LoadingMore" ? <ActivityIndicator /> : null
      }
    />
  );
}

Auth-aware rendering

If the auth integration provides Convex auth helpers, use them for UI gating:

• Authenticated
• Unauthenticated
• AuthLoading

These improve UX, but they are not security controls. The backend still decides access.

Error handling in screens

Prefer three explicit states:

1. loading, 2. empty, 3. loaded with data.

Then add an error strategy appropriate for the app:

• inline message for expected issues,
• toast or banner for mutation failures,
• error boundary for render-time query failures.

A useful mental model is that Convex gives you the data transport and reactivity, but you still own product-grade UX.

Path alias and import pitfalls

Common generated API imports:

• ../convex/_generated/api
• ../../convex/_generated/api
• @/convex/_generated/api if the project already defines that alias

Do not assume @/ exists. Verify the project config first.

Screen checklist

Before finishing a screen that talks to Convex:

• [ ] useQuery handles undefined.
• [ ] Mutations are awaited.
• [ ] The screen imports from generated API references.
• [ ] Empty states exist for zero-data cases.
• [ ] The list is paginated if it can grow without bound.
• [ ] Protected data is backed by server-side authorization.
• [ ] No extra Convex client is created inside the component tree.

Convex function patterns for Expo projects

Use this reference when deciding how to implement backend logic and where that logic should live.

Choose the right function type

query

Use for deterministic reads.

Good for:

• loading lists,
• loading detail views,
• computing derived read-only values from Convex data.

Rules:

• no writes,
• no external network access,
• no Date.now()-driven behaviour inside the query,
• and keep it fast.

mutation

Use for writes.

Good for:

• create, update, delete,
• toggles,
• transactional state changes,
• bookkeeping fields such as createdAt and updatedAt.

Rules:

• do not call third-party APIs from mutations,
• keep business rules server-side,
• and validate all client inputs.

action

Use when you need things outside the normal deterministic runtime.

Good for:

• calling external APIs,
• using Node-only packages,
• AI SDKs,
• Stripe,
• sending email,
• filesystem or crypto APIs that require the Node runtime,
• post-processing uploads.

Rules:

• if the file starts with "use node", keep that file action-only,
• call writes via ctx.runMutation(...),
• call reads via ctx.runQuery(...),
• and avoid mixing runtime modes in the same file.

Internal functions

Use internalQuery, internalMutation, and internalAction when logic should never be callable from a client.

Good for:

• backfills,
• privileged state transitions,
• action helpers,
• scheduled jobs,
• expensive maintenance logic,
• and refactoring public wrappers into smaller internal operations.

Minimum standard for public functions

Every public query, mutation, and action should have:

• args,
• clear backend authorization if the data is not public,
• and preferably returns.

For mutations that do not return useful data, explicitly return null.

Starter template

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

const taskDoc = v.object({
  _id: v.id("tasks"),
  _creationTime: v.number(),
  userId: v.id("users"),
  title: v.string(),
  status: v.union(
    v.literal("todo"),
    v.literal("doing"),
    v.literal("done"),
  ),
  createdAt: v.number(),
});

export const listMine = query({
  args: {
    userId: v.id("users"),
  },
  returns: v.array(taskDoc),
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .order("desc")
      .take(50);
  },
});

export const create = mutation({
  args: {
    userId: v.id("users"),
    title: v.string(),
  },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    const title = args.title.trim();
    if (!title) throw new Error("Task title cannot be empty");

    return await ctx.db.insert("tasks", {
      userId: args.userId,
      title,
      status: "todo",
      createdAt: Date.now(),
    });
  },
});

export const markDone = internalMutation({
  args: {
    taskId: v.id("tasks"),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.patch(args.taskId, { status: "done" });
    return null;
  },
});

Thin wrappers, shared helpers

Keep wrappers small. Put repeated logic in plain TypeScript helpers.

Good structure

• convex/tasks.ts for public wrappers
• convex/lib/auth.ts for identity lookup helpers
• convex/lib/tasks.ts for business rules or validation helpers
• convex/tasksActions.ts for external API or Node-runtime work

Why this matters

• easier to test,
• less duplicated auth and ownership logic,
• easier to reuse from actions or background jobs,
• safer refactors.

Auth pattern

If data is user-scoped, do not trust a client-supplied userId unless the function verifies it.

Safer patterns:

• read the current identity with ctx.auth.getUserIdentity(),
• resolve the corresponding user document,
• and then scope queries or writes with the verified user.

When many functions need the same protection, create custom wrappers with convex-helpers. See references/auth.md and references/components-and-helpers.md.

Expected failures vs exceptional failures

For expected product-level failures:

• return null or a discriminated result shape when that fits the API,
• or throw a ConvexError with a structured payload when the caller should handle it as an expected failure.

Examples:

• unauthenticated access,
• trying to edit a resource the user does not own,
• validation that depends on current database state,
• or “not found” for a user-selected record.

Use plain Error for unexpected failures when structure is not needed.

Avoid these anti-patterns

1. Unvalidated public functions

Bad:

export const create = mutation({
  handler: async (ctx, args) => {
    return await ctx.db.insert("tasks", args);
  },
});

Why it is bad:

• no input validation,
• no output contract,
• easy to accidentally expose fields you did not intend.

2. Query logic that depends on wall-clock time

Bad:

export const listReleased = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db
      .query("posts")
      .withIndex("by_released_at", (q) => q.lte("releasedAt", Date.now()))
      .take(50);
  },
});

Safer options:

• pass now from the client as an argument when needed,
• or precompute a field such as isReleased with scheduled updates.

3. Full-table scans with .filter()

Bad:

const project = await ctx.db
  .query("projects")
  .filter((q) => q.eq(q.field("slug"), args.slug))
  .unique();

Better:

• add .index("by_slug", ["slug"]),
• use .withIndex("by_slug", ...).

4. Unbounded .collect() on feeds

Bad:

return await ctx.db.query("notifications").collect();

Better:

• use .take(50) for small bounded lists,
• or paginated queries for inboxes, feeds, and chat.

5. Mixing "use node" with queries or mutations

Bad:

"use node";

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

export const createTask = mutation({
  // invalid in a Node-runtime-only file
});

Correct pattern:

• keep regular query and mutation functions in normal runtime files,
• create a sibling somethingActions.ts file for "use node" actions.

Action pattern for external services

convex/aiActions.ts

"use node";

import { action } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "convex/values";

export const generateAndStoreSummary = action({
  args: {
    noteId: v.id("notes"),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    const note = await ctx.runQuery(internal.notes.getForSummariser, {
      noteId: args.noteId,
    });

    if (!note) {
      throw new Error("Note not found");
    }

    const summary = `Summary for ${note.title}`;

    await ctx.runMutation(internal.notes.storeSummary, {
      noteId: args.noteId,
      summary,
    });

    return null;
  },
});

Pagination backend pattern

import { paginationOptsValidator } from "convex/server";
import { query } from "./_generated/server";
import { v } from "convex/values";

export const listByProject = query({
  args: {
    projectId: v.id("projects"),
    paginationOpts: paginationOptsValidator,
  },
  handler: async (ctx, args) => {
    return await ctx.db
      .query("tasks")
      .withIndex("by_project", (q) => q.eq("projectId", args.projectId))
      .order("desc")
      .paginate(args.paginationOpts);
  },
});

Review checklist

• [ ] Correct function type chosen.
• [ ] Public functions validate args.
• [ ] Public functions expose deliberate returns.
• [ ] Protected data is authorised on the backend.
• [ ] Shared logic lives in helpers or wrappers.
• [ ] External APIs and Node-only SDKs live in actions.
• [ ] No unbounded .collect() on growing data.
• [ ] No Date.now() inside query logic.
• [ ] All promises are awaited.
• [ ] Internal functions are used to reduce public surface area where appropriate.

Migration patterns for Convex in Expo apps

Use this reference when changing schemas or gradually moving from another backend without breaking live clients.

Migration priorities

1. keep the app working during the transition, 2. make each migration step restart-safe, 3. avoid one-shot breaking changes unless the app is still throwaway, 4. reduce public blast radius by using internal functions for migration logic.

Preferred migration strategy: additive first

Safe changes

These are usually straightforward:

• add a new optional field,
• add a new table,
• add a new index,
• add a new internal function,
• add a new public read path while old ones still work.

Risky changes

These usually need a staged rollout:

• making an optional field required,
• changing field types,
• renaming a field,
• splitting one table into multiple related tables,
• merging multiple shapes into one,
• removing fields that old clients still read.

Pattern 1: optional field -> backfill -> required field

Step 1

Add the field as optional.

users: defineTable({
  name: v.string(),
  bio: v.optional(v.string()),
})

Step 2

Backfill missing rows with an internal mutation or internal action.

import { internalMutation } from "./_generated/server";
import { v } from "convex/values";

export const backfillUserBio = internalMutation({
  args: {
    batchSize: v.optional(v.number()),
  },
  returns: v.object({
    processed: v.number(),
  }),
  handler: async (ctx, args) => {
    const batchSize = args.batchSize ?? 100;
    const users = await ctx.db.query("users").take(batchSize);

    let processed = 0;

    for (const user of users) {
      if (user.bio !== undefined) continue;
      await ctx.db.patch(user._id, { bio: "" });
      processed += 1;
    }

    return { processed };
  },
});

Step 3

Run the backfill repeatedly until no rows remain.

Step 4

Make the field required only after all data is compliant and old clients are updated.

Pattern 2: rename a field

Suppose name becomes displayName.

Safer rollout

1. add displayName as optional, 2. backfill from name, 3. update readers to prefer displayName ?? name, 4. update writers to write both fields for a period, 5. remove reads of name, 6. finally remove name from the schema.

This dual-read and dual-write period is what keeps mobile clients from breaking during staggered releases.

Pattern 3: split nested or overloaded data into proper tables

Example:

• old posts.tags: string[]
• new tags table plus postTags join table

Safer rollout

1. add the new tables and indexes, 2. keep the old field temporarily, 3. backfill relationships in batches, 4. update readers to use the new tables, 5. update writers to populate only the new shape, 6. remove the old field once all readers are migrated.

Pattern 4: move from another backend to Convex gradually

Good strategy:

1. keep the old system for legacy features, 2. add new features in Convex first, 3. migrate one domain at a time, 4. dual-read where needed, 5. cut traffic over feature by feature.

This works well when moving from Firebase, Supabase, a REST backend, or a custom database.

Batch processing guidance

For large tables:

• process in batches,
• make the batch idempotent,
• log enough state to know what has already been migrated,
• avoid reading the entire table into memory,
• and prefer resumable jobs over one huge mutation.

Scheduled migration pattern

When a migration is expensive, schedule or repeatedly invoke a small internal unit of work instead of trying to finish everything in one request.

Good for:

• media metadata backfills,
• adding derived state fields,
• rebuilding search or denormalised views,
• moving historical records.

Validation rules during migrations

While migrating:

• keep validators accurate for each active shape,
• do not expose a public function that accepts both legacy and new shapes unless you truly need it,
• and make deprecation windows deliberate rather than accidental.

Mobile-client-specific note

Expo clients can lag behind the backend because users do not update instantly.

That means:

• avoid removing fields immediately after changing the app,
• keep old read paths alive long enough,
• and assume some users will run an older build against the new backend for a while.

Review checklist

• [ ] The change has been decomposed into additive steps.
• [ ] Backfills are idempotent and can be resumed.
• [ ] Public clients are not forced onto a breaking schema in one step.
• [ ] Mobile release lag has been accounted for.
• [ ] Old reads and writes are removed only after the rollout is complete.
• [ ] Internal functions are used for migration mechanics where appropriate.

Production hardening checklist for Expo + Convex

Use this before preview or production release.

Environment and deployment

• [ ] EXPO_PUBLIC_CONVEX_URL exists locally and in the correct EAS environments.
• [ ] Preview and production builds point at the intended Convex deployments.
• [ ] Team members know which deployment maps to each build profile.
• [ ] npx convex dev is not the only place the deployment URL is documented.

Provider and generated code

• [ ] Exactly one ConvexReactClient exists.
• [ ] The provider is mounted at the real app root.
• [ ] convex/_generated/ is current and committed or ignored according to the team’s workflow.
• [ ] All frontend calls import from generated API references.

Backend safety

• [ ] Public functions define args.
• [ ] Public functions expose deliberate returns where practical.
• [ ] Protected resources enforce authorization on the backend.
• [ ] Internal-only workflows use internal functions.
• [ ] All promises are awaited.
• [ ] External APIs or Node-only packages live in actions, not mutations or queries.

Performance

• [ ] Large or growing lists use pagination.
• [ ] Heavy lookups use indexes rather than full scans.
• [ ] Queries do not rely on Date.now() or other nondeterministic time checks.
• [ ] Unbounded .collect() calls have been replaced where needed.
• [ ] Common ownership or tenant filters have matching indexes.

Developer experience and maintainability

• [ ] TypeScript strict mode is enabled or there is a documented reason it is not.
• [ ] @convex-dev/eslint-plugin is installed and configured.
• [ ] The project runs lint and typecheck successfully.
• [ ] Repeated auth or tenancy logic has been centralised.
• [ ] Runtime boundaries are obvious: normal files vs "use node" action files.

Expo UX

• [ ] Loading, empty, and error states exist for Convex-backed screens.
• [ ] Mutation pending states are acceptable on slow mobile networks.
• [ ] Offline or reconnect behaviour has been tested on device where relevant.
• [ ] Screens do not assume useQuery is immediately loaded.

Files and media

• [ ] Uploads use upload URLs instead of forcing bytes through standard mutations.
• [ ] Metadata writes are awaited after uploads.
• [ ] Protected media queries and serving URLs are authorized.
• [ ] Large asset libraries paginate.

Migration readiness

• [ ] Pending schema changes are additive or staged.
• [ ] Old clients will not break if they run against the new backend.
• [ ] Backfills are resumable and safe to re-run.

Suggested commands

python scripts/validate_project.py --root <project-root> --fail-on-warning
cd <project-root> && npm run lint
cd <project-root> && npm run typecheck

Adjust the npm scripts to match the project.

Final gut check

If someone new cloned the app and followed the documented setup, would they end up with:

• a working provider,
• a working deployment URL,
• a generated API folder,
• secure backend access patterns,
• and no obvious scaling traps?

If not, tighten the docs or the code before release.

Schema and index design for Expo + Convex

Convex works schemaless, but an Expo app benefits from adding convex/schema.ts early once the data model stops changing every few minutes.

Design principles

1. Model documents as flat, relational records

Prefer:

• tasks.userId
• comments.taskId
• memberships.organizationId

over deeply nested arrays of objects inside a single document.

2. Add indexes for real query shapes

Index the fields you actually query on:

• ownership: userId
• membership: organizationId, teamId
• status tabs: userId + status
• time or ordering: userId + createdAt, channelId + createdAt
• lookup keys: tokenIdentifier, email, slug

3. Keep arrays bounded

Arrays are fine for small, naturally limited collections such as:

• user roles,
• a few tags,
• feature flags,
• recent device IDs.

Do not store large, growing sets such as comments, messages, or child records inside arrays.

4. Design around access rules

If every query is user-scoped, put userId directly on the table and index it.

If data is multi-tenant, include the org or team ID directly on every tenant-owned table rather than inferring tenancy indirectly.

Schema template

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

export default defineSchema({
  users: defineTable({
    tokenIdentifier: v.string(),
    email: v.string(),
    name: v.string(),
    imageUrl: v.optional(v.string()),
    role: v.union(v.literal("user"), v.literal("admin")),
  })
    .index("by_token", ["tokenIdentifier"])
    .index("by_email", ["email"]),

  projects: defineTable({
    ownerId: v.id("users"),
    organizationId: v.optional(v.id("organizations")),
    name: v.string(),
    status: v.union(
      v.literal("active"),
      v.literal("archived"),
      v.literal("draft"),
    ),
    createdAt: v.number(),
  })
    .index("by_owner", ["ownerId"])
    .index("by_org", ["organizationId"])
    .index("by_owner_and_status", ["ownerId", "status"]),

  tasks: defineTable({
    projectId: v.id("projects"),
    assigneeId: v.optional(v.id("users")),
    title: v.string(),
    status: v.union(
      v.literal("todo"),
      v.literal("doing"),
      v.literal("done"),
    ),
    createdAt: v.number(),
  })
    .index("by_project", ["projectId"])
    .index("by_assignee", ["assigneeId"])
    .index("by_project_and_status", ["projectId", "status"]),
});

Query shape mapping

Before adding an index, write the query in plain English.

• “List my active projects” → by_owner_and_status
• “Find a user by token identifier” → by_token
• “Show tasks for a project in todo state” → by_project_and_status
• “Load messages in a channel newest first” → by_channel plus .order("desc")

If you cannot describe the query shape clearly, the schema is usually not ready yet.

Prefer indexes over .filter()

For large or growing tables:

• use .withIndex(...),
• then use .order(...), .take(...), .first(), or .paginate(...).

Use .filter() only when:

• the result set is already small and bounded, or
• the logic truly cannot be expressed via indexes.

If you do filter in TypeScript, start from a deliberately small result set rather than the whole table.

Pagination rule of thumb

Switch from take(...) to pagination when any of the following are true:

• the list is user-generated and unbounded,
• the screen is a feed, inbox, notification list, or message list,
• the product expects hundreds of rows,
• or the UI naturally wants infinite scroll or “load more”.

See references/frontend-patterns.md for the frontend hook and references/functions.md for the backend query pattern.

Time-based data

Safe pattern

Store timestamps on writes:

• createdAt
• updatedAt
• scheduledFor
• releasedAt

and query them deterministically.

Unsafe pattern

Do not call Date.now() inside a query to decide what should be returned right now.

Instead:

• pass time as an argument from the client, or
• maintain a coarser state field such as isReleased, isExpired, or dueToday, updated by a scheduled function.

Example: messages with pagination

import { paginationOptsValidator } from "convex/server";
import { query } from "./_generated/server";
import { v } from "convex/values";

export const listByChannel = query({
  args: {
    channelId: v.id("channels"),
    paginationOpts: paginationOptsValidator,
  },
  handler: async (ctx, args) => {
    return await ctx.db
      .query("messages")
      .withIndex("by_channel", (q) => q.eq("channelId", args.channelId))
      .order("desc")
      .paginate(args.paginationOpts);
  },
});

Common mistakes

Missing index on a foreign key

If a feature constantly looks up projectId, userId, or organizationId, index it from the start.

Nested objects growing without bound

If comments or checklist items can grow, they deserve their own table.

Too many redundant indexes

Do not create every possible index “just in case”. Add indexes around observed access patterns.

Migrating directly to a breaking schema

For live data, add optional fields first, backfill, and only then make them required. See references/migrations.md.

Review checklist

• [ ] Each protected resource stores the ownership or tenancy field it needs.
• [ ] Each common lookup has a matching index.
• [ ] Bounded arrays stay bounded.
• [ ] Large lists use pagination rather than unbounded collection.
• [ ] Query code does not rely on Date.now() for live filtering.
• [ ] The schema is easy to explain in terms of product features rather than implementation accidents.

Sources used to rewrite this skill

Checked or reviewed on 2026-03-12.

Agent Skills guidance

• Agent Skills specification
• Optimizing skill descriptions
• Evaluating skills
• Using scripts
• The complete skill-building guide supplied with this task

Convex and Expo guidance

• Expo guide for using Convex
• Convex React Native and deployment URL docs
• Convex validation, actions, internal functions, error handling, and pagination docs
• Convex best practices and ESLint docs
• Convex Clerk integration docs
• Convex Auth docs
• Convex file upload guidance
• Convex blog post on uploading files from React Native or Expo

Local plugin inputs folded into this rewrite

From the attached convex-agent-plugins repository, the rewrite incorporates guidance inspired by:

• argument-validation.mdc
• async-handling.mdc
• authentication-checks.mdc
• custom-functions-for-auth.mdc
• function-organization.mdc
• no-date-now-in-queries.mdc
• query-optimization.mdc
• schema-design.mdc
• use-components-for-encapsulation.mdc
• use-eslint-always.mdc
• use-node-for-actions.mdc
• use-pagination-for-large-datasets.mdc

and the bundled skills:

• auth-setup
• components-guide
• convex-helpers-guide
• convex-quickstart
• function-creator
• migration-helper
• schema-builder

Intent of the rewrite

This skill deliberately tightens:

• frontmatter quality and trigger specificity,
• progressive disclosure through references,
• script interfaces for agentic use,
• Convex safety defaults,
• Expo-specific environment handling,
• and evaluation scaffolding.

Tasks example for Expo + Convex

Use this as the smallest end-to-end proof that the stack is wired correctly.

What this proves

A successful run confirms all of the following:

• npx convex dev is running,
• convex/_generated/ exists,
• the Expo app can reach the deployment URL,
• the root provider is mounted correctly,
• and frontend imports are pointing at generated API references.

1. Seed data

Create sampleData.jsonl in the project root:

{"text": "Buy groceries", "isCompleted": true}
{"text": "Go for a swim", "isCompleted": true}
{"text": "Integrate Convex", "isCompleted": false}

Import it:

npx convex import --table tasks sampleData.jsonl

2. Add a schema

convex/schema.ts

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

export default defineSchema({
  tasks: defineTable({
    text: v.string(),
    isCompleted: v.boolean(),
  }),
});

This table is small enough for a starter example. Add indexes later if you query by owner, status, or team.

3. Add functions

convex/tasks.ts

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

const taskDoc = v.object({
  _id: v.id("tasks"),
  _creationTime: v.number(),
  text: v.string(),
  isCompleted: v.boolean(),
});

export const list = query({
  args: {},
  returns: v.array(taskDoc),
  handler: async (ctx) => {
    return await ctx.db.query("tasks").order("desc").take(50);
  },
});

export const add = mutation({
  args: { text: v.string() },
  returns: v.id("tasks"),
  handler: async (ctx, args) => {
    const text = args.text.trim();
    if (!text) {
      throw new Error("Task text cannot be empty");
    }

    return await ctx.db.insert("tasks", {
      text,
      isCompleted: false,
    });
  },
});

export const toggle = mutation({
  args: {
    taskId: v.id("tasks"),
    isCompleted: v.boolean(),
  },
  returns: v.null(),
  handler: async (ctx, args) => {
    await ctx.db.patch(args.taskId, {
      isCompleted: args.isCompleted,
    });
    return null;
  },
});

Why take(50) instead of .collect()?

For a starter example, take(50) keeps the query bounded. If the list can grow without limit, switch to a paginated query and usePaginatedQuery.

4. Add a screen

Use a relative import that matches the screen location.

If the screen file is app/index.tsx

import { api } from "../convex/_generated/api";
import { useMutation, useQuery } from "convex/react";
import { useState } from "react";
import {
  ActivityIndicator,
  FlatList,
  Pressable,
  Text,
  TextInput,
  View,
} from "react-native";

export default function IndexScreen() {
  const tasks = useQuery(api.tasks.list);
  const addTask = useMutation(api.tasks.add);
  const toggleTask = useMutation(api.tasks.toggle);
  const [text, setText] = useState("");

  if (tasks === undefined) {
    return (
      <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
        <ActivityIndicator />
      </View>
    );
  }

  return (
    <View style={{ flex: 1, padding: 24, gap: 16 }}>
      <View style={{ gap: 8 }}>
        <Text style={{ fontSize: 28, fontWeight: "700" }}>Tasks</Text>
        <Text style={{ color: "#666" }}>
          If this renders, the Expo and Convex wiring is working.
        </Text>
      </View>

      <View style={{ flexDirection: "row", gap: 8 }}>
        <TextInput
          value={text}
          onChangeText={setText}
          placeholder="Add a task"
          style={{
            flex: 1,
            borderWidth: 1,
            borderColor: "#ddd",
            borderRadius: 10,
            paddingHorizontal: 12,
            paddingVertical: 10,
          }}
        />
        <Pressable
          onPress={async () => {
            const trimmed = text.trim();
            if (!trimmed) return;
            await addTask({ text: trimmed });
            setText("");
          }}
          style={{
            justifyContent: "center",
            borderRadius: 10,
            paddingHorizontal: 14,
            paddingVertical: 10,
            backgroundColor: "#111",
          }}
        >
          <Text style={{ color: "white", fontWeight: "600" }}>Add</Text>
        </Pressable>
      </View>

      <FlatList
        data={tasks}
        keyExtractor={(task) => task._id}
        renderItem={({ item }) => (
          <Pressable
            onPress={() =>
              toggleTask({
                taskId: item._id,
                isCompleted: !item.isCompleted,
              })
            }
            style={{
              borderWidth: 1,
              borderColor: "#eee",
              borderRadius: 12,
              padding: 14,
              marginBottom: 10,
            }}
          >
            <Text
              style={{
                fontSize: 16,
                textDecorationLine: item.isCompleted ? "line-through" : "none",
              }}
            >
              {item.text}
            </Text>
          </Pressable>
        )}
      />
    </View>
  );
}

If the screen lives under src/app, change the generated API import accordingly.

5. Expected behaviour

• tasks is undefined on the first render.
• It then resolves to an array.
• Pressing Add creates a task and the list updates reactively.
• Pressing a task toggles completion and the UI updates without manual refetching.

6. Quick debug checklist

If it fails:

1. confirm npx convex dev is running, 2. confirm convex/_generated/api exists, 3. confirm the provider is mounted at the app root, 4. confirm the screen imports from the generated API, 5. confirm the client sees EXPO_PUBLIC_CONVEX_URL, 6. run python scripts/validate_project.py --root <project-root>.

Optional helper script

You can scaffold the files above with:

python scripts/scaffold_tasks_example.py --root <project-root>
python scripts/scaffold_tasks_example.py --root <project-root> --write

Add --ui-file app/index.tsx or another target path if you also want a screen scaffolded.

Troubleshooting Expo + Convex

Use this file when the integration mostly exists but something is clearly off.

useQuery(...) stays undefined

Remember: undefined is normal during the initial load.

If it never resolves, check these in order:

1. npx convex dev is running. 2. convex/_generated/api exists. 3. the provider is mounted at the app root. 4. the app can read process.env.EXPO_PUBLIC_CONVEX_URL. 5. the query reference comes from generated api. 6. the backend function is compiling successfully.

EXPO_PUBLIC_CONVEX_URL is undefined

Most common causes:

• .env.local was never created because npx convex dev has not run,
• Metro was not restarted after the env file changed,
• the code uses the wrong variable name,
• a different .env* file overrides the expected value.

convex/_generated is missing or stale

Causes:

• npx convex dev is not running,
• TypeScript errors in convex/ stopped generation,
• or the working directory for npx convex dev was wrong.

Fix:

1. run npx convex dev from the Expo project root, 2. fix any backend compile errors, 3. wait for generation to complete.

“Cannot find module '../convex/_generated/api'”

Usually one of these:

• the relative path is wrong for the screen’s location,
• the project uses src/app but the import assumes app,
• or convex/_generated has not been generated yet.

The app crashes after adding Convex

Common causes:

• provider is mounted too low in the tree,
• multiple ConvexReactClient instances exist,
• or a screen renders before the root provider is available.

Query is stale or behaves strangely around time

If a query uses Date.now() or new Date() internally, the reactivity model will not behave the way you expect.

Fix:

• pass time as an argument,
• or maintain a stored status field updated elsewhere.

Slow screens or expensive queries

Look for:

• .filter() on large tables,
• unbounded .collect(),
• missing indexes on foreign keys,
• or screens trying to load entire feeds at once.

Fix:

• add indexes,
• switch to .withIndex(...),
• use take(...) or paginated queries,
• and update the screen to usePaginatedQuery where appropriate.

Node or third-party SDK errors in backend files

If a query or mutation tries to use:

• fetch to third-party APIs,
• Buffer,
• crypto,
• Stripe,
• OpenAI,
• filesystem access,

move that logic into an action. If the file needs Node APIs, start it with "use node" and keep it action-only.

Auth says signed in but backend is unauthenticated

Check all three layers:

1. client auth provider is mounted correctly, 2. Convex auth provider configuration matches the client provider, 3. backend functions actually read and enforce ctx.auth.getUserIdentity().

Do not trust only the UI provider’s “signed in” flag.

File uploads succeed but the app cannot find the file later

Check:

• the second metadata mutation was awaited,
• the correct storageId was persisted,
• the query returning file data is authorized,
• the UI is asking for the correct file record.

ESLint or validation warnings about public functions

Typical fixes:

• add args: { ... },
• add returns: ...,
• move internal-only logic to internal functions,
• replace scans with indexes,
• or split "use node" code into a separate action file.

Remote agent or CI environment cannot run npx convex dev

Only cloud agents or CI-like environments that cannot log in should consider:

CONVEX_AGENT_MODE=anonymous npx convex dev

Do not add this by default for local development. Local work should usually use your normal authenticated Convex setup.

Quick recovery sequence

When the project is messy and you need to stabilise it fast:

1. stop Metro, 2. start npx convex dev, 3. run python scripts/validate_project.py --root <project-root>, 4. fix env issues, 5. fix provider placement, 6. fix generated API imports, 7. restart Metro, 8. re-test with a small known-good query such as the tasks example.

Useful commands

python scripts/validate_project.py --root <project-root>
python scripts/validate_project.py --root <project-root> --json
python scripts/scaffold_tasks_example.py --root <project-root>