Skip to main content

Prerequisites

Use Node.js 24 or later and an existing React + TypeScript app. The client examples below use Vite and its VITE_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.
The commands below use pnpm exec to run the locally installed CLIs. With npm, use npx instead; with Yarn, use yarn; with Bun, use bunx.

TypeScript configuration

Confect requires strict: true in the TypeScript configuration that covers your Confect files. exactOptionalPropertyTypes: true is optional but recommended:
tsconfig.json
See Effect Schema’s explanation of exactOptionalPropertyTypes for how it affects optional properties and schema validation.

Usage

1

Set up your Convex dev deployment

Initialize your development deployment and the convex/ directory, then exit after the first successful sync:
Follow the prompts to configure your deployment. See Convex’s local deployment guide if you want to develop locally without an account.
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.
Define a tableβ€”one file per table under 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
Codegen will assemble every 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 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
Use Confect’s React hooks alongside your Confect public refs to call your Confect functions.
src/App.tsx
Start your React app with its development command (for example, 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.

Example project

See a full, working example project here.