Configuring Convex
To add Convex to a codebase you'll need to
- Install the
convex
npm package - Create a new Convex project with
npx convex init
- 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.
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.