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:
.env.local
file with yourCONVEX_ADMIN_KEY
in the project root directoryconvex.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