Skip to main content
The Convex client setup is the foundation for integrating Convex into your React application. It creates a real-time connection to your Convex backend and provides authentication support.

​
Installation

All React components automatically include the client setup files. When you install any component, these files are added to your project: 
npx shadcn@latest add https://convex-ui.vercel.app/r/password-based-auth-react
This creates:
  • lib/convex/client.ts - Convex client instance
  • lib/convex/provider.tsx - React provider component

​
Client Configuration

The client is configured to connect to your Convex deployment using environment variables.

​
lib/convex/client.ts

import { ConvexReactClient } from "convex/react";

const convexUrl = (import.meta as any).env.VITE_CONVEX_URL as string;

export const convex = new ConvexReactClient(convexUrl);
For Vite-based React apps, environment variables must be prefixed with VITE_ to be accessible in the browser.

​
Provider Setup

The provider wraps your application and enables Convex queries, mutations, and authentication.

​
lib/convex/provider.tsx

import { ConvexAuthProvider } from "@convex-dev/auth/react";
import { ConvexReactClient } from "convex/react";
import { ReactNode } from "react";

const convex = new ConvexReactClient(
  (import.meta as any).env.VITE_CONVEX_URL as string,
);

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

​
Usage

Wrap your application root with the ConvexClientProvider: 
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import { ConvexClientProvider } from './lib/convex/provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ConvexClientProvider>
      <App />
    </ConvexClientProvider>
  </React.StrictMode>,
)

​
Environment Variables

Create a .env file in your project root:
.env
VITE_CONVEX_URL=https://your-deployment.convex.cloud
CONVEX_DEPLOYMENT=your-deployment-name
1
Get Your Convex URL
2
Run npx convex dev to start the Convex development server. The deployment URL will be displayed in the terminal.
3
Add to Environment
4
Copy the URL (e.g., https://happy-animal-123.convex.cloud) and add it to your .env file as VITE_CONVEX_URL.
5
Restart Dev Server
6
Restart your Vite dev server to load the new environment variables.

​
Features

Real-time Queries

Automatically subscribes to database changes and re-renders components when data updates.

Authentication

Integrates Convex Auth for user authentication with password and OAuth providers.

Type Safety

Full TypeScript support with generated types from your Convex schema.

Optimistic Updates

Update UI instantly while mutations process in the background.

​
Using Convex Hooks

Once the provider is set up, you can use Convex hooks anywhere in your app: 
import { useQuery, useMutation } from "convex/react";
import { api } from "./convex/_generated/api";
import { useAuthActions } from "@convex-dev/auth/react";

function MyComponent() {
  // Query data (real-time)
  const messages = useQuery(api.messages.list, { roomId: "general" });
  
  // Mutations
  const sendMessage = useMutation(api.messages.send);
  
  // Authentication
  const { signIn, signOut } = useAuthActions();
  
  // ...
}

​
API Reference

​
ConvexClientProvider

The main provider component that wraps your application.
​
children
ReactNode
required
Your application components

​
convex

The Convex client instance. You can import this directly if you need to access the client imperatively: 
import { convex } from "./lib/convex/client";

// Use client directly
const result = await convex.query(api.myFunction.get, { id: "123" });

​
Troubleshooting

Make sure you’ve created a .env file with VITE_CONVEX_URL and restarted your dev server. Vite only loads environment variables on startup.
This is normal while the initial connection is being established. Check the connection status with useConvex() hook or add loading states to your components.
Run npx convex dev to generate TypeScript types from your Convex functions. Make sure the convex/_generated directory is created.

​
Next Steps

Password Auth

Add email/password authentication to your app

Social Auth

Enable GitHub and Google sign-in

Realtime Chat

Build a real-time chat component

File Upload

Add file upload with Convex storage

Build docs developers (and LLMs) love

Get started for freeTalk to us