Using Convex

Edit page

Add a database to your app with Convex.

Convex is a backend platform for building reactive apps with a realtime database, server functions, file storage, search, scheduling, and type-safe client libraries without the need for cluster management, SQL, or ORMs.

The EAS CLI integration can create and connect the Convex project for you. It replaces the manual setup steps where you install the package, create a Convex team and project, copy deployment URLs, and configure EAS environment variables.

Prerequisites

3 requirements

Expo account

EAS CLI

Install EAS CLI globally with npm install -g eas-cli.

Expo project linked to EAS

Create an Expo project and link it to EAS with eas init.

Connect Convex with EAS

Run the EAS CLI integration command

From your Expo project directory, run:

Terminal

- eas integrations:convex:connect

The command will prompt for a Convex deployment region, project name, and team name when needed. It only asks for a team name when it needs to create a new Convex team connection.

You can also pass values explicitly:

Terminal

- eas integrations:convex:connect --region aws-us-east-1 --team-name "Your-team-name" --project-name "your-app"

The integration command:

Installs the convex package with npx expo install convex
Creates a Convex team connection for your EAS account, or reuses an existing one
Creates a Convex project and deployment for the current Expo app
Writes CONVEX_DEPLOY_KEY and EXPO_PUBLIC_CONVEX_URL to .env.local
Creates or updates the EXPO_PUBLIC_CONVEX_URL EAS project environment variable for the production, preview, and development environments
Sends an invitation to your verified email so you can claim the Convex team and open the Convex dashboard

Start Convex locally

After the integration command finishes, start the Convex dev server:

Terminal

- npx convex dev

This creates the local convex directory if your project does not have one yet, generates the typed API files, and syncs your Convex functions with your deployment while it runs.

Add a Convex provider

Create a Convex client with the deployment URL that the EAS integration wrote to .env.local, then wrap your app in ConvexProvider.

For an Expo Router project, update src/app/_layout.tsx:

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

Query Convex from your app

Add a query function in the convex directory:

convex/tasks.ts

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

export const get = query({
  args: {},
  handler: async ctx => {
    return await ctx.db.query('tasks').collect();
  },
});

Then call it from your app with useQuery:

src/app/index.tsx

import { api } from '@/convex/_generated/api';
import { useQuery } from 'convex/react';
import { Text, View } from 'react-native';

export default function Index() {
  const tasks = useQuery(api.tasks.get);

  return (
    <View>
      {tasks?.map(task => (
        <Text key={task._id}>{task.text}</Text>
      ))}
    </View>
  );
}

To learn more about how Convex works, including database documents, functions, and client subscriptions, see the Convex overview:

Convex overview

Learn the core Convex concepts behind database documents, functions, and realtime client updates.

Manage the integration

Use these commands to inspect or manage the Convex integration later:

Terminal

- eas integrations:convex:project

- eas integrations:convex:dashboard

- eas integrations:convex:team

- eas integrations:convex:team:invite

If you remove the link with eas integrations:convex:project:delete or eas integrations:convex:team:delete, EAS removes its integration metadata. These commands do not destroy resources on Convex.

Troubleshooting

Accept a team invite sent to a different email

The Convex team invitation goes to the verified email on your Expo account, but Convex only supports signing in with Google or GitHub. If your Google or GitHub email is different, the invitation page says the invited email address has not been added to your Convex account. Navigating away from that page leaves you in a separate Convex account that does not contain your project.

Convex invitation page showing that the email address associated with the team invitation has not been added to your account

To accept the invite from your existing Convex account:

On the invitation page (or in the Convex dashboard's profile settings), click Add email and enter the invited email address.
Open the verification email that Convex sends to that address and verify it.
Return to the invitation link and reload the page, or sign out and open the invitation link again.
Accept the invite. The team and project now appear in your Convex account.

The flow can look like it failed after verifying the email. The invitation page does not update until you reload or reopen it.