Skip to main content

Configuring Convex

To add Convex to a codebase you'll need to

  1. Install the convex npm package
  2. Create a new Convex project with npx convex init
  3. Configure your client to communicate with your Convex deployment.

Install Convex and create a Convex project​

From your project root, run the following to install the Convex library and create a new Convex project.

npm install convex
npx convex init

Creating a new project will step you through creating a Convex account if you don't already have one.

Your new project includes a production deployment, located at a URL displayed during the init process and potentially also saved to a .env file. You can find the URLs of all deployments in a project by visiting the settings section of each deployment in the Convex dashboard.

Configure the Convex Client​

Construct a Convex React client by passing in the URL of the Convex deployment. There should generally be a single Convex client in a frontend application.

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

const address = import.meta.env.VITE_CONVEX_URL;

const convex = new ConvexReactClient(address);

While this URL can be hardcoded, it's convenient to use an environment variable to determine which Convex backend to initialize the client with. In development, your app can connect to a personal development Convex deployment. In production, it can connect to a separate production Convex deployment.

Use an environment variable name accessible from your client code according to the frontend framework or bundler you're using.

Choosing environment variable names

To avoid unintentionally exposing secret environment variables in frontend code, many bundlers require environment variables referenced in frontend code to use a specific prefix.

Vite requires environment variables used in frontend code start with VITE_, so the code above uses VITE_CONVEX_URL.

Create React App requires environment variables used in frontend code to begin with REACT_APP_, so REACT_APP_CONVEX_URL would be a good name.

Next.js requires them to begin with NEXT_PUBLIC_, so NEXT_PUBLIC_CONVEX_URL would be a good name.

Bundlers provide different ways to access these variables too: while Vite uses import.meta.env.VARIABLE_NAME, many other tools like Next.js use the Node.js-ism process.env.VARIABLE_NAME

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

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

.env files are a common way to wire up different environment variable values in development and production environments. If a .env or .env.production file is present, npx convex init will offer to add a variable to it. If you add a .env file later, you'll need to add the environment variable yourself.

.env
NEXT_PUBLIC_CONVEX_URL=https://guiltless-dog-960.convex.cloud

# examples of other environment variables that might be passed to the frontend
NEXT_PUBLIC_SENTRY_DSN=https://123abc@o123.ingest.sentry.io/1234
NEXT_PUBLIC_LAUNCHDARKLY_SDK_CLIENT_SIDE_ID=01234567890abcdef

To use a development Convex deployment, add that URL to a .env.local file which overrides the .env file. If a .env.local file is present, Convex CLI commands that use development deployments will offer to update this file.

Wire up the React provider​

Wrap your application component in a ConvexProvider that uses the Convex client you created.

Place this provider high enough in the React component tree to available everywhere you want communicate with your Convex backend. In Next.js for example, the _app.jsx component is a good spot.

<ConvexProvider client={convex}>
  <App />
</ConvexProvider>

Custom package.json dev script​

The Convex dev server watches the local filesystem, pushing your Convex functions to your deployment and updating generated code each time you modify the code for your backend.

When developing locally you'll need to run both the Convex dev server with npx convex dev and your frontend development server, e.g. npm run dev.

Instead of using two separate terminals, we recommend using a single command that runs both the frontend and backend.

Modify the your package.json script to run both your development server and npx convex dev at the same time. A tool like concurrently or npm-run-all can be used to do this.

For example, with concurrently (install it with npm add --dev concurrently) and Vite, the dev script might look like:

  "scripts": {
    "dev": "concurrently 'vite' 'convex dev'"
  },

Now running npm run dev will run both development servers.