Quick Start

Three steps to production: Set up shadcn/ui, initialize Convex, add a component. You’ll have a working app in minutes.

Prerequisites

Before you begin, make sure you have:

Node.js 18+ installed on your machine
A React project (Next.js, Vite, TanStack Start, or React Router)
Basic familiarity with React and TypeScript

Starting from scratch? The shadcn/ui setup will create a new project for you.

Step 1: Set up shadcn/ui

Convex UI components are built on shadcn/ui. Choose your framework and follow the official setup guide:

Next.js

Recommended for full-stack apps with SSR

Vite

Fast development for SPAs and client-side apps

TanStack Start

Modern routing with React Router foundation

Already using shadcn/ui? Skip to Step 2. Convex UI works with your existing setup.

The shadcn/ui setup will:

Configure Tailwind CSS
Set up your components.json config file
Install base UI dependencies
Create your component directory structure

Step 2: Initialize Convex

Install Convex and initialize your project:

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

No account required for local development. Convex runs entirely on your machine until you’re ready to deploy.

The convex dev command will:

Create the convex directory

Initializes convex/ with starter files and schema

Generate environment variables

Adds NEXT_PUBLIC_CONVEX_URL (or VITE_CONVEX_URL) to your .env.local file

Start the dev server

Launches a local Convex backend with hot reload

Deploy functions automatically

Watches for changes and redeploys instantly

What gets created

After initialization, your project will have:

your-project/
├── convex/
│   ├── _generated/         # Auto-generated TypeScript types
│   └── schema.ts           # Database schema (initially empty)
├── .env.local              # Convex deployment URL
└── convex.json             # Convex configuration

Keep npx convex dev running while you develop. It provides hot reload for backend functions.

Step 3: Add your first component

Now you can add any Convex UI component. Let’s start with realtime chat:

Next.js
React (Vite)
TanStack Start

npx shadcn@latest add "https://convex-ui.vercel.app/r/realtime-chat-nextjs"

npx shadcn@latest add "https://convex-ui.vercel.app/r/realtime-chat-react"

npx shadcn@latest add "https://convex-ui.vercel.app/r/realtime-chat-tanstack"

This installs:

Frontend

components/realtime-chat.tsx
components/chat-message.tsx
hooks/use-realtime-chat.tsx

Backend

convex/schema.ts (messages table)
convex/messages.ts (queries & mutations)

Step 4: Use the component

Import and use the chat component in your app:

Next.js
React (Vite)
TanStack Start

app/page.tsx

import { RealtimeChat } from "@/components/realtime-chat";

export default function Home() {
  return (
    <main className="container mx-auto p-8">
      <RealtimeChat 
        roomName="general" 
        username="Alice" 
      />
    </main>
  );
}

src/App.tsx

import { RealtimeChat } from "@/components/realtime-chat";

function App() {
  return (
    <div className="container mx-auto p-8">
      <RealtimeChat 
        roomName="general" 
        username="Alice" 
      />
    </div>
  );
}

export default App;

routes/index.tsx

import { RealtimeChat } from "@/components/realtime-chat";

export default function IndexRoute() {
  return (
    <div className="container mx-auto p-8">
      <RealtimeChat 
        roomName="general" 
        username="Alice" 
      />
    </div>
  );
}

Open multiple browser windows to see messages sync in realtime!

Add authentication

For a more complete app, add password-based authentication:

Next.js
React (Vite)
TanStack Start

npx shadcn@latest add "https://convex-ui.vercel.app/r/password-based-auth-nextjs"

npx shadcn@latest add "https://convex-ui.vercel.app/r/password-based-auth-react"

npx shadcn@latest add "https://convex-ui.vercel.app/r/password-based-auth-tanstack"

This adds complete authentication flows:

✅ Login form with email/password
✅ Signup with validation
✅ Password reset flow
✅ Protected route middleware
✅ User session management
✅ Convex Auth configuration

Configure email provider

For password reset emails, configure Resend in the Convex dashboard:

Get a Resend API key

Add to Convex dashboard

Go to your project settings → Environment Variables

Set required variables

AUTH_RESEND_KEY=re_...
AUTH_EMAIL_FROM=[email protected]

OAuth providers (GitHub, Google) require additional setup. See the authentication docs for callback URL configuration.

What’s next?

Explore components

Browse all available components including file uploads, cursors, and presence

Customize styling

Modify Tailwind classes or update your theme in components.json

Extend backend functions

Learn how to write custom queries and mutations in Convex

Deploy to production

Push your app live with npx convex deploy

Troubleshooting

Components not installing correctly

Try deleting your components.json file and running the shadcn/ui init command again for your framework. This resets your configuration to the latest defaults.

rm components.json
npx shadcn@latest init

Convex dev server not starting

Make sure you have Node.js 18+ installed:

node --version

If you’re behind a firewall, you may need to configure proxy settings. Check the Convex troubleshooting guide.

TypeScript errors in generated files

Restart your TypeScript server in VS Code:

Press Cmd/Ctrl + Shift + P
Type “TypeScript: Restart TS Server”
Press Enter

The _generated folder updates automatically when convex dev is running.

Environment variables not working

Make sure your .env.local file has the correct variable names:Next.js:

NEXT_PUBLIC_CONVEX_URL=https://...
CONVEX_DEPLOYMENT=dev:...

Vite, TanStack, React Router:

VITE_CONVEX_URL=https://...
CONVEX_DEPLOYMENT=dev:...

Restart your dev server after changing environment variables.

Still having issues? Check the FAQ or visit the Convex Discord for help.

Get Started

Next.js Components

React Components

TanStack Components

Prerequisites

Step 1: Set up shadcn/ui

Next.js

Vite

TanStack Start

Step 2: Initialize Convex

What gets created

Step 3: Add your first component

Frontend

Backend

Step 4: Use the component

Add authentication

Configure email provider

What’s next?

Explore components

Customize styling

Extend backend functions

Deploy to production

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Next.js Components

React Components

TanStack Components

​Prerequisites

​Step 1: Set up shadcn/ui

Next.js

Vite

TanStack Start

​Step 2: Initialize Convex

​What gets created

​Step 3: Add your first component

Frontend

Backend

​Step 4: Use the component

​Add authentication

​Configure email provider

​What’s next?

Explore components

Customize styling

Extend backend functions

Deploy to production

​Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Step 1: Set up shadcn/ui

Step 2: Initialize Convex

What gets created

Step 3: Add your first component

Step 4: Use the component

Add authentication

Configure email provider

What’s next?

Troubleshooting