Set Up Convex Auth

To start a new project from scratch with Convex and Convex Auth, run

npm create convex@latest

and choose React (Vite) or Next.js and then Convex Auth.

Otherwise follow the guide below.

This guide assumes you have a working Convex app. If not, follow our React, Next.js or React Native quickstart (opens in a new tab) first.

Install the NPM library

npm install @convex-dev/auth @auth/core

This also installs @auth/core, which you will use during provider configuration later.

Run the initialization command

npx @convex-dev/auth

This sets up your project for authenticating via the library.

Alternatively you can perform these steps manually: Manual Setup

Add authentication tables to your schema

Convex Auth assumes you have several tables set up with specific indexes.

You can add these tables to your schema (opens in a new tab) via the authTables export:

convex/schema.ts

import { defineSchema } from "convex/server";
import { authTables } from "@convex-dev/auth/server";
 
const schema = defineSchema({
  ...authTables,
  // Your other tables...
});
 
export default schema;

Set up the React provider

Replace ConvexProvider from convex/react with ConvexAuthProvider from @convex-dev/auth/react:

src/main.tsx

import { ConvexAuthProvider } from "@convex-dev/auth/react";
import React from "react";
import ReactDOM from "react-dom/client";
import { ConvexReactClient } from "convex/react";
import App from "./App.tsx";
import "./index.css";
 
const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
 
ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <ConvexAuthProvider client={convex}>
      <App />
    </ConvexAuthProvider>
  </React.StrictMode>,
);

The initial setup is done. Next you'll choose and configure authentication methods.

Introduction Manual Setup