FAQ

Can’t find what you’re looking for? Join the Convex Discord or check the Convex documentation.

Getting started

How does Convex UI work?

Convex UI uses the shadcn/ui registry system to install components directly into your project:

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

This single command:

Downloads React components to your src/components/ directory
Adds Convex backend functions to your convex/ directory
Installs any required npm dependencies
Creates environment variable templates

Unlike traditional npm packages, these files become your code. Customize anything—no upstream updates to worry about.

Will it overwrite my existing files?

No. The CLI is safe to run in existing projects:

Scenario	Behavior
New file	Created automatically
Existing file (same content)	Skipped
Existing file (different content)	You’re prompted to choose

Always commit your changes to Git before adding components. This gives you a clean diff to review what changed.

Can I use this in an existing project?

Yes! Convex UI works great with existing projects. The components integrate alongside your current code.Recommended workflow:

Commit your current work

Make sure your Git working directory is clean

Review installation

Check what files will be added before running the command

Install component

Run the add command for your chosen component

Review changes

Use git diff to see exactly what was added or modified

If you already have Convex or shadcn/ui configured, the components will use your existing setup.

Do I need to set up Convex first?

Yes, but it only takes two commands:

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

That’s it. No dashboard configuration, no account creation (for local development), no complex setup.See the Quick Start guide for complete setup instructions.

What's the difference between Convex UI and shadcn/ui?

shadcn/ui provides UI primitives (buttons, inputs, dialogs) with no backend logic.Convex UI builds on shadcn/ui and adds:

Convex backend functions (queries, mutations)
Database schema definitions
Authentication logic
Realtime subscriptions
Full-stack features out of the box

You need both: shadcn/ui for the base components, Convex UI for the features.

Technical questions

How does realtime work?

Convex provides automatic realtime subscriptions through reactive queries. When data changes anywhere, your UI updates instantly.

// This component automatically re-renders when messages change
const messages = useQuery(api.messages.list, { roomId: "general" });

No extra setup required:

❌ No WebSocket configuration
❌ No polling intervals
❌ No cache invalidation logic
❌ No optimistic update boilerplate

The realtime connection is built into every useQuery hook. This powers features like live chat, presence indicators, and collaborative cursors.

Read more about Convex reactivity in the official docs.

How does local development work?

Local development with Convex is seamless:

Start dev server

Run npx convex dev in your terminal

Edit backend functions

Modify files in the convex/ directory

Changes sync instantly

Functions hot reload without restarting the server

Deploy when ready

Run npx convex deploy to push to production

Your database schema lives in code (convex/schema.ts) and is version-controlled with your app.

The Convex dashboard provides a data browser and logs viewer at convex.dev/dashboard.

What authentication options are available?

Convex UI provides two authentication patterns using @convex-dev/auth:

Password-based authentication

Email/password sign-in
User registration with validation
Forgot password flow
Password reset via email
Email verification

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

GitHub sign-in
Google sign-in
Extensible for additional providers

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

Both patterns include secure session management, protected routes, and user profile handling.

Can I use my own database instead of Convex?

No. Convex UI components are tightly integrated with Convex’s reactive query system. The realtime functionality, type generation, and backend functions all depend on Convex.If you need traditional REST APIs or a different database, consider using standard shadcn/ui components and building your own backend integration.

Convex itself is flexible and can integrate with external services via HTTP actions. See external APIs in Convex.

Why React only?

Three reasons:

shadcn/ui is React-based — Convex UI builds directly on top of it
Convex has first-class React support — Hooks like useQuery and useMutation make realtime seamless
It’s established tooling — Not a new library, just React components + Convex working together

The backend functions in convex/ work with any frontend. Only the React components are framework-specific. You could build a Vue or Svelte frontend that calls the same Convex functions.

Framework support

Which frameworks are supported?

Convex UI supports multiple React frameworks:

Framework	Status	Auth	Storage	Realtime
Next.js	✅ Full support	✅	✅	✅
React (Vite)	✅ Full support	✅	✅	✅
TanStack Start	✅ Full support	✅	✅	✅
React Router v7	✅ Full support	✅	✅	✅

Each framework has its own:

Client configuration (lib/convex/client.ts)
Provider setup (lib/convex/provider.tsx)
Routing patterns (pages vs routes)
Environment variable prefixes (NEXT_PUBLIC_ vs VITE_)

I already have shadcn/ui installed

Perfect! You’re ready to go. Just run any add command to install Convex UI components:

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

The components will use your existing components.json configuration and theme settings.

I already have Convex set up

Great! Your existing Convex configuration will be used automatically. The components add new files to your convex/ directory alongside your existing functions.

If you have an existing convex/schema.ts, you may need to merge schema definitions manually. The CLI will prompt you if there are conflicts.

Can I use this with App Router (Next.js)?

Yes! All Next.js components support both App Router and Pages Router.App Router example:

app/page.tsx

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

export default function Home() {
  return <RealtimeChat roomName="general" username="Alice" />;
}

Pages Router example:

pages/index.tsx

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

export default function Home() {
  return <RealtimeChat roomName="general" username="Alice" />;
}

I used an AI code generator (v0, Bolt, Lovable)

If your AI-generated app uses Convex, you can add Convex UI components directly. The CLI works the same way—just be mindful of existing auth or schema configurations.Recommended workflow:

Review AI-generated code

Check what’s already in convex/schema.ts and convex/auth.ts

Commit to Git

Save your current state before making changes

Add Convex UI components

Run the add command for your desired component

Resolve conflicts

Merge any schema conflicts manually if prompted

Troubleshooting

Components aren't connecting to Convex

Check your environment variables:Next.js (.env.local):

NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
CONVEX_DEPLOYMENT=dev:your-project-name

Vite, TanStack, React Router (.env or .env.local):

VITE_CONVEX_URL=https://your-project.convex.cloud
CONVEX_DEPLOYMENT=dev:your-project-name

For authentication components, also add:

CONVEX_SITE_URL=http://localhost:3000

Run npx convex dev to see your actual deployment URL in the terminal output.

Schema type errors after adding components

If you see TypeScript errors in convex/schema.ts, you likely have conflicting table definitions.How to fix:

Open convex/schema.ts

Look for duplicate table definitions

Merge duplicates

Combine fields from both definitions into one

Check indexes

Ensure all index names are unique across tables

Validate schema

Run npx convex dev to check for errors

Each table can only be defined once. If you need multiple features, merge their schema definitions.

Authentication isn't working

Common auth issues and solutions:

Issue	Solution
”Invalid URL” error	Check `CONVEX_SITE_URL` matches your dev server (e.g., `http://localhost:3000`)
OAuth redirect fails	Verify callback URLs in GitHub/Google provider settings
Session not persisting	Ensure provider wraps your app in `layout.tsx` or `_app.tsx`
”Not authenticated” in API calls	Check that auth middleware is properly configured

Next.js App Router:

app/layout.tsx

import { ConvexAuthNextjsServerProvider } from "@convex-dev/auth/nextjs/server";

export default function RootLayout({ children }) {
  return (
    <ConvexAuthNextjsServerProvider>
      {children}
    </ConvexAuthNextjsServerProvider>
  );
}

Realtime updates aren't working

Make sure:

convex dev is running — The dev server must be active for realtime to work
You’re using useQuery — Only queries (not actions) provide realtime subscriptions
Provider is configured — Your app must be wrapped with ConvexProvider
Network connection — Check browser console for connection errors

Test the connection:

import { useConvex } from "convex/react";

const convex = useConvex();
console.log(convex.connectionState()); // Should be "connected"

File uploads failing

For the dropzone component, verify:

Storage is enabled — It’s enabled by default in Convex
File size limits — Default max is 1GB, configurable in Convex settings
CORS configuration — Check convex/http.ts for proper CORS headers
Authentication — File uploads may require an authenticated user

Example storage query:

convex/files.ts

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

export const getUrl = query({
  args: { storageId: v.id("_storage") },
  handler: async (ctx, { storageId }) => {
    return await ctx.storage.getUrl(storageId);
  },
});

TypeScript errors in _generated folder

The convex/_generated folder is auto-generated. Never edit it manually.To fix TypeScript errors:

Restart Convex dev server

Stop convex dev and run it again

Restart TypeScript server

In VS Code: Cmd/Ctrl + Shift + P → “TypeScript: Restart TS Server”

Clear generated files

Delete convex/_generated and let it regenerate

If errors persist, check for syntax errors in your convex/schema.ts or function files.

Need more help?

Convex Discord

Get help from the Convex community and team

Convex Docs

Learn more about Convex queries, mutations, and architecture

shadcn/ui Docs

Explore base UI components and styling options

GitHub Issues

Report bugs or request features for Convex UI

Get Started

Next.js Components

React Components

TanStack Components

Getting started

Technical questions

Password-based authentication

Framework support

Troubleshooting

Need more help?

Convex Discord

Convex Docs

shadcn/ui Docs

GitHub Issues

Build docs developers (and LLMs) love

Get Started

Next.js Components

React Components

TanStack Components

​Getting started

​Technical questions

​Password-based authentication

​Social authentication (OAuth)

​Framework support

​Troubleshooting

​Need more help?

Convex Discord

Convex Docs

shadcn/ui Docs

GitHub Issues

Build docs developers (and LLMs) love

Getting started

Technical questions

Password-based authentication

Social authentication (OAuth)

Framework support

Troubleshooting

Need more help?