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