Skip to main content

Quick Start

1. Create a new project

npx create-next-app@latest -e convex my-convex-app

This creates a new Next.js project in the directory my-convex-app/ containing a simple webapp which uses Convex functions from the directory my-convex-app/convex/.

2. Log in

npx convex login

3. Create your new Convex deployment

npx convex init

This will generate:

  1. .env.local file with your CONVEX_ADMIN_KEY in the project root directory
  2. convex.json file with connection configuration in the project root directory

4. Deploy your Convex functions

npx convex push

This pushes your Convex functions, runs codegen, and typechecks those functions. You'll want to run this whenever you update your Convex functions.

5. You're ready to go!

That's it! You can view your app with npm run dev.

Quick reference

Here are a few code snippets and commands you might need in one convenient place. You can see their full explanation in Basic Concepts.

Set up Convex in your React app:

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

const convex = new ConvexReactClient(convexConfig.origin);
<ConvexProvider client={convex}>
<App />
</ConvexProvider>

Use a Convex query:

convex/myQueryFunction.ts
import { query } from "./_generated/server";

export default query(async ({ db }) => {
// Load data with `db` here!
});
src/MyApp.tsx
import { useQuery } from "../convex/_generated/react";

function MyApp() {
// Call the query from within a React component!
const data = useQuery("myQueryFunction");
return <MyComponent data={data} />;
}

Use a Convex mutation:

convex/myMutationFunction.ts
import { mutation } from "./_generated/server";

export default mutation(async ({ db }) => {
// Edit data with `db` here!
});
src/MyApp.tsx
import { useMutation } from "../convex/_generated/react";

function MyApp() {
// Call the mutation within a React event handler!
const myMutation = useMutation("myMutationFunction");
return <MyComponent onClick={myMutation} />;
}

Use the CLI:

Manage Deployments

  • Log in: npx convex login
  • Create a new deployment: npx convex init
  • Deactivate a deployment: npx convex deactivate
  • Recreate deployment config files: npx convex reinit --deployment-name <name>

Write Code

  • Push Convex functions: npx convex push
  • Update generated code: npx convex codegen
  • Typecheck functions: npx convex typecheck
  • Modify authentication settings: npx convex auth <subcommand>

Misc

  • Open the dashboard: npx convex dashboard
  • Open the docs: npx convex docs