Next.js Quickstart

Convex + Next.js

Convex is an all-in-one backend and database that integrates quickly and easily with Next.js.

Once you've gotten started, see how to set up hosting, server rendering, and auth.

To get setup quickly with Convex and Next.js run

npm create convex@latest

or follow the guide below.

Learn how to query data from Convex in a Next.js app using the App Router and

Alternatively see the Pages Router version of this quickstart.

Create a Next.js app
Create a Next.js app using the npx create-next-app command.
Choose the default option for every prompt (hit Enter).
npx create-next-app@latest my-app
Install the Convex client and server library
To get started, install the convex package.
Navigate to your app and install convex.
cd my-app && npm install convex
Set up a Convex dev deployment
Next, run npx convex dev. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.
It will also create a convex/ folder for you to write your backend API functions in. The dev command will then continue running to sync your functions with your dev deployment in the cloud.
npx convex dev

Create sample data for your database

In a new terminal window, create a sampleData.jsonl file with some sample data.

sampleData.jsonl
{"text": "Buy groceries", "isCompleted": true}
{"text": "Go for a swim", "isCompleted": true}
{"text": "Integrate Convex", "isCompleted": false}

Add the sample data to your database
Use the import command to add a tasks table with the sample data into your Convex database.
npx convex import --table tasks sampleData.jsonl
Expose a database query
In the convex/ folder, add a new file tasks.ts with a query function that loads the data.
Exporting a query function from this file declares an API function named after the file and the export name: api.tasks.get.
convex/tasks.ts
TS
import { query } from "./_generated/server"; export const get = query({ args: {}, handler: async (ctx) => { return await ctx.db.query("tasks").collect(); }, });

Create a client component for the Convex provider

For <ConvexProvider> to work on the client, ConvexReactClient must be passed to it.

In the app/ folder, add a new file ConvexClientProvider.tsx with the following code. This creates a client component that wraps <ConvexProvider> and passes it the <ConvexReactClient>.

app/ConvexClientProvider.tsx
TS
"use client";

import { ConvexProvider, ConvexReactClient } from "convex/react";
import { ReactNode } from "react";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export function ConvexClientProvider({ children }: { children: ReactNode }) {
  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
}

Wire up the ConvexClientProvider

In app/layout.tsx, wrap the children of the body element with the <ConvexClientProvider>.

app/layout.tsx
TS
import type { Metadata } from "next";
import { Geist, Geist_Mono } from "next/font/google";
import "./globals.css";
import { ConvexClientProvider } from "./ConvexClientProvider";

const geistSans = Geist({
  variable: "--font-geist-sans",
  subsets: ["latin"],
});

const geistMono = Geist_Mono({
  variable: "--font-geist-mono",
  subsets: ["latin"],
});

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
        <ConvexClientProvider>{children}</ConvexClientProvider>
      </body>
    </html>
  );
}

Display the data in your app

In app/page.tsx, use the useQuery() hook to fetch from your api.tasks.get API function.

app/page.tsx
TS
"use client";

import Image from "next/image";
import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";

export default function Home() {
  const tasks = useQuery(api.tasks.get);
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      {tasks?.map(({ _id, text }) => <div key={_id}>{text}</div>)}
    </main>
  );
}

Start the app
Run your Next.js development server, open http://localhost:3000 in a browser, and see the list of tasks.
npm run dev

See the complete Next.js documentation.