Prerequisites
Use Node.js 24 or later and an existing React + TypeScript app. The client examples below use Vite and itsVITE_CONVEX_URL environment
variable. Run all commands from your appβs root directory.
Installation
If pnpm reports ignored build scripts for
esbuild, run pnpm approve-builds
and approve only esbuild, then rerun pnpm install. Keep this approval
scoped to your project rather than enabling all dependency scripts.pnpm exec to run the locally installed CLIs. With npm,
use npx instead; with Yarn, use yarn; with Bun, use bunx.
TypeScript configuration
Confect requiresstrict: true in the TypeScript configuration that covers your
Confect files. exactOptionalPropertyTypes: true is optional but recommended:
tsconfig.json
exactOptionalPropertyTypes
for how it affects optional properties and schema validation.
Usage
1
Set up your Convex dev deployment
Initialize your development deployment and the Follow the prompts to configure your deployment. See Convexβs
local deployment guide if you
want to develop locally without an account.
convex/ directory, then exit
after the first successful sync:2
Define your database schema
Not every Effect
Schema is valid for use in Confect. See
Schema Restrictions for more
information about whatβs permitted and whatβs not.confect/tables/, where the filename is the table name (so filenames must be valid JS identifiers and may not start with _). Each file must default-export a Table; codegen reads module.default and applies the filename as the table name. From other modules (e.g. specs), default-import the codegen-emitted wrapper at confect/_generated/tables/<name> to reach the tableβs derived Schemas (notes.Doc, notes.Fields).confect/tables/notes.ts
confect/tables/*.ts into a DatabaseSchema (in confect/_generated/schema.ts) and a Convex deploy SchemaDefinition (in confect/_generated/convexSchema.ts) for youβyou never write a confect/schema.ts. It also emits a confect/_generated/id.ts module exporting a type-safe Id constructor (Id("notes")) for cross-table references.3
Generate your table bindings
Before adding a function spec, generate the table schemas and services that
your specs and implementations will import:This creates
confect/_generated/, including id.ts, tables/notes.ts,
schema.ts, and services.ts.This tutorial generates table bindings before you write the functions. If
your table, spec, and implementation files are already complete, one codegen
run can generate everything without this separate step.4
Define your Confect API spec
Create a
GroupSpec and add some functions to it.confect/notes.spec.ts
5
Implement your Confect functions
Create a
GroupImpl and implement its functions. Each spec needs a sibling
implementation before you run codegen again; otherwise codegen reports a
missing implementation.confect/notes.impl.ts
GroupImpl.finalize only typechecks once every function declared by the spec has a corresponding FunctionImpl, so it acts as a per-group completeness check.Generate the function refs and Convex functions now that both the spec and
implementation exist:6
Start your Confect app
Keep Confectβs generated files in sync as you edit:In another terminal, start your Convex dev deployment:
7
Call your Confect functions from your React app
Set Use Confectβs React hooks alongside your Confect public refs to call your Confect functions.Start your React app with its development command (for example,
VITE_CONVEX_URL in your Vite appβs environment to the development
deployment URL printed by Convex. Set up the Convex React client and provider:src/main.tsx
src/App.tsx
pnpm dev
in a Vite project). Enter a note and click Create note. The note should
appear in the list, confirming that the mutation and reactive query work.