Convex Client and Backend SDK

Common errors

• Error: VITE_CONVEX_URL is not defined

  cause The environment variable for the Convex deployment URL is missing or incorrectly named.
  fix Create a `.env` file in your project root with `VITE_CONVEX_URL=https://your-convex-url.convex.cloud` (or `CONVEX_URL` for Node.js environments) and restart your development server.

• ctx.auth.getUserIdentity() returns null in a query

  cause The client-side authentication process has not completed by the time the `useQuery` hook attempts to fetch data, or the user is not signed in.
  fix Ensure the user is authenticated before calling queries that rely on `ctx.auth.getUserIdentity()`. Use Convex's `Authenticated` React component or handle the `null` identity gracefully within your client-side component, showing a loading or unauthenticated state.

• Type errors in api imports

  cause The TypeScript types for your Convex backend functions (located in `convex/_generated/api.d.ts`) are out of sync with your latest backend code.
  fix Run `npx convex dev` (or `npx convex codegen` if not running `dev`) to regenerate the TypeScript types. Ensure your `convex/` directory is properly set up.

• Write conflict: Optimistic concurrency control

  cause A Convex mutation failed to commit because the underlying data it read changed due to another concurrent mutation. This leads to retries and can indicate contention on specific documents.
  fix Refactor mutations to read less data, use more specific indexed queries, or reduce concurrent writes to the same document. For high-contention scenarios, rethink the data model to spread writes across more documents.

Warnings

• breaking Convex function arguments changed from multiple positional arguments to a single arguments object. Additionally, the schema builder `s` moved from `convex/schema` to `v` in `convex/values`, and several client APIs (`ConvexReactClient`, `ConvexHttpClient`) were updated for consistency.
  Fix: Update backend functions to accept a single object for arguments. Migrate schema definitions to use `import { v } from 'convex/values;'`. Review client-side API calls for `ConvexReactClient` and `ConvexHttpClient`.
• breaking The `ctx.db.get`, `patch`, `replace`, and `delete` functions now require the table name as the first argument, e.g., `ctx.db.get("tableName", id)`. While previous syntax is still supported, it will be deprecated.
  Fix: Update database interaction calls in your backend functions to explicitly include the table name as the first argument. Automatic migration tools (ESLint rule, codemod) are available.
• deprecated Node.js 18 support is being deprecated, with new projects defaulting to Node.js 20. Existing Node.js 18 projects will be automatically migrated to Node.js 20 by October 22, 2025.
  Fix: Ensure your development and deployment environments are using Node.js 20 or later to avoid future compatibility issues and take advantage of new features.
• gotcha When using `useQuery` within React components, `ctx.auth.getUserIdentity()` can initially return `null` if the Convex client has not yet fully authenticated, even if the user is logged in.
  Fix: Wrap components containing authenticated `useQuery` calls with Convex's `Authenticated` component or explicitly handle `null` results from the query on the client-side, potentially rendering a loading state or fallback UI.
• gotcha React Hooks cannot be called conditionally. Using `useQuery` inside an `if` statement or conditional block will lead to runtime errors.
  Fix: For conditional data fetching, pass the special string `'skip'` as the arguments to `useQuery` when the query should not run, for example: `useQuery(api.myFunc, condition ? { arg: 'value' } : 'skip');`
• gotcha Circular imports in your Convex backend files, especially involving `schema.ts`, can lead to 'Undefined validator' errors at runtime.
  Fix: Refactor your import structure to break circular dependencies. Often, this involves moving common validators or table definitions into a separate file that does not import back from `schema.ts`.

Install

• npm install convex npm
• yarn add convex yarn
• pnpm add convex pnpm

Imports

• ConvexReactClient
  wrong:

  const ConvexReactClient = require('convex/react');

  correct:

  import { ConvexReactClient } from 'convex/react';

  The Convex client for React applications. Typically instantiated once and passed to `ConvexProvider`.
• useQuery
  wrong:

  import useQuery from 'convex/react';

  correct:

  import { useQuery } from 'convex/react';

  React hook for fetching real-time data from Convex queries. Requires `api` object from `_generated/api`.
• query
  wrong:

  import { query } from 'convex/react';

  correct:

  import { query } from 'convex/server';

  Used in Convex backend files (e.g., `convex/myFunctions.ts`) to define read-only database functions.
• mutation
  wrong:

  import { mutation } from 'convex';

  correct:

  import { mutation } from 'convex/server';

  Used in Convex backend files to define write operations to the database. These run as transactions.
• v
  wrong:

  import { s } from 'convex/schema';

  correct:

  import { v } from 'convex/values';

  Validator object for defining schema and function arguments. Renamed from `s` in `convex/schema` since v0.13.0.
• api

  import { api } from '../convex/_generated/api';

  Generated client-side API object for calling Convex backend functions. Path is relative to your client code.

Quickstart

This quickstart demonstrates how to set up the Convex React client, connect to a Convex backend, and display real-time data fetched using the `useQuery` hook within a React component. It assumes a basic backend query `getTasks` is defined.

import React from 'react';
import { ConvexReactClient, ConvexProvider, useQuery } from 'convex/react';
import { api } from '../convex/_generated/api'; // Adjust path as needed

// Initialize the Convex client
const convexUrl = process.env.VITE_CONVEX_URL ?? 'https://your-convex-url.convex.cloud'; // Replace with your actual URL or env var
const convex = new ConvexReactClient(convexUrl);

// Backend function definition (e.g., in convex/tasks.ts)
/*
  import { query } from './_generated/server';
  import { v } from 'convex/values';

  export const getTasks = query({
    args: { status: v.optional(v.string()) },
    handler: async (ctx, args) => {
      return await ctx.db.query('tasks')
        .filter(q => args.status ? q.eq(q.field('status'), args.status) : true)
        .collect();
    },
  });
*/

interface Task {
  _id: string;
  text: string;
  status: 'todo' | 'done';
}

function TaskList() {
  // Fetch tasks in real-time. The component re-renders when data changes.
  const tasks = useQuery(api.tasks.getTasks, { status: 'todo' });

  if (tasks === undefined) {
    return <div>Loading tasks...</div>;
  }

  if (tasks.length === 0) {
    return <div>No tasks to display.</div>;
  }

  return (
    <div>
      <h1>Todo List</h1>
      <ul>
        {tasks.map((task: Task) => (
          <li key={task._id}>{task.text}</li>
        ))}
      </ul>
    </div>
  );
}

export default function App() {
  return (
    <ConvexProvider client={convex}>
      <TaskList />
    </ConvexProvider>
  );
}