Convex is a comprehensive backend application platform offering a real-time database, serverless functions (queries, mutations, actions), and client libraries for JavaScript/TypeScript, with strong support for React. The current stable version is 1.36.0, with frequent precompiled releases indicating rapid development and continuous improvements. A key differentiator is its real-time reactivity, where client-side `useQuery` hooks automatically update whenever the underlying database data changes, eliminating manual subscription management. It provides end-to-end type safety, optional schema definitions, and a TypeScript-first approach for both backend function definitions and client-side consumption. The platform includes SDKs for defining backend logic, integrating with React, and handling authentication with providers like Auth0 and Clerk. Convex aims to simplify full-stack development by unifying the database and backend logic within a single reactive environment.
npm install convexVerified import paths — ran on the pinned version, not inferred.
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.
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`.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.
Ensure your development and deployment environments are using Node.js 20 or later to avoid future compatibility issues and take advantage of new features.
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.
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');`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`.
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.
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.
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.
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.