Quickstart

Create a new Next.js project

To create 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/, run

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

In a new terminal, run this command from the same directory:

npm run dev

npx convex dev watches the local filesystem, pushing your Convex functions to your dev deployment and updated generated code each time you modify files in my-convex-app/convex/. The first time you run the command you'll create a new Convex project that you'll be able to see on your dashboard.

Once your app is running (npm run dev in a new terminal), visit localhost:3000 in a browser to see it.

Add Convex to an existing React app

From your project root, install Convex and run the convex dev command in a different terminal than your dev server.

npm install convex
npx convex dev

npx convex dev watches the local filesystem, pushing your Convex functions to your dev deployment and updated generated code each time you modify files in my-convex-app/convex/.

Create a Convex React client object and wrap your application component in a Convex Provider:

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

const convex = new ConvexReactClient(clientConfig);

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

Now when you write query and mutation functions in the newly created convex/ folder to access your data...

convex/sendMessage.js

import { mutation } from "./_generated/server";

export default mutation(({ db }, body, author) => {
  const message = { body, author };
  db.insert("messages", message);
});

convex/listMessages.js

import { query } from "./_generated/server";

export default query(async ({ db }) => {
  return await db.query("messages").collect();
});

...you can use these queries and mutations in React components.

src/MyApp.jsx

import { useQuery } from "../convex/_generated/react";
import { useMutation } from "../convex/_generated/react";

function MyApp() {
  // data will be `undefined` while the query is first loading
  const data = useQuery("listMessages");
  const sendMessage = useMutation("sendMessage");
  const sendHello = () => sendMessage("Hello!", "me");
  return (
    <div>
      <MyListView data={data} />
      <button onClick={sendHello}>click me!</button>
    </div>
  );
}