Project Structure

​

confect/

​

_generated/

​

convexSchema.ts

Contains the Convex deploy-time SchemaDefinition (a single defineSchema({...}) call) assembled from every confect/tables/*.ts module. convex/schema.ts re-exports its default so Convex’s CLI and convex-test find it where they expect. You should never import this file directly from your own code — use _generated/schema.ts for runtime needs.

​

id.ts

Contains a type-constrained Id constructor whose only argument is the union of your table names — for example, Id("users") returns the Schema for an _id value in the users table. Use this when defining cross-table references (e.g. a userId: Id("users") field) and inside spec args/returns schemas. The type-level constraint catches typos at compile time, replacing the loosely-typed GenericId.GenericId("users") form.

​

registeredFunctions/

Contains one module per group (for example registeredFunctions/notes_and_random/notes.ts), each exporting that group’s functions in a form the Convex CLI can consume. These modules are consumed by the generated convex/ files; you should not need to import them directly.

​

refs.ts

Contains a single default Refs export, which is a map of your Convex functions and their function names and args/returns Schemas. Use this to invoke your Convex functions from the client or inside Convex functions using the *Runner services (QueryRunner, MutationRunner, and ActionRunner).

​

schema.ts

Contains the runtime DatabaseSchema — the codec-lookup view of your tables. Impls import it and pass it to FunctionImpl.make / GroupImpl.make. It is generated from confect/tables/*.ts and intentionally avoids any convex/server import so a runtime cold start never evaluates defineSchema(...). Each table’s field-schema is constructed lazily on the first access to its Fields, Doc, or tableDefinition and then cached, so a function only pays the schema-construction cost at cold start for the tables it actually touches via db.table(name). Use this when a test or a non-codegen-generated module needs to refer to your DatabaseSchema type or value.

​

tables/

Contains one wrapper module per user-authored table (for example tables/notes.ts for confect/tables/notes.ts). Each wrapper applies the filename-derived table name to the Table defined in confect/tables/<name>.ts and re-exports it as the default. Specs, impls, and other consumers should default-import from confect/_generated/tables/<name> to reach a table’s Doc, Fields, and tableName properties — for example, import notes from "../_generated/tables/notes" and then notes.Doc.

​

services.ts

Contains Effect service wrappers for Convex platform capabilities, scoped to your app’s database schema. Use these in your function implementation handlers. See Services for a full list.

​

spec.ts

Contains your assembled Confect spec — every function group, of any runtime (including Node action groups) — used to build refs.ts.

​

auth.ts

Optional Corresponds 1:1 with convex/auth.config.ts. Use this to configure auth.

​

crons.ts

Optional Expects a default CronJobs export defining your cron jobs.

​

http.ts

Optional Expects a default Convex HttpRouter export. Construct this using Confect’s HttpApi.make and @effect/platform’s HTTP API modules.

​

tables/

Required Defines your database tables, one file per table. The filename is the table name — confect/tables/notes.ts defines a table called notes — so filenames must be valid JS identifiers and may not start with _ (Convex reserves underscore-prefixed names for system tables). Each module must default-export a Table (built with Table.make(...)); codegen reads module.default, validates the filename, and applies it as the table name to produce _generated/tables/<name>.ts. Other modules import from the wrapper, not directly from tables/. Codegen also scans this directory to produce _generated/schema.ts (runtime), _generated/convexSchema.ts (deploy), and _generated/id.ts (the cross-table Id constructor). See Schema.

​

*.spec.ts/*.impl.ts

Required Your Convex API is defined as colocated *.spec.ts/*.impl.ts pairs, one pair per group. Each file’s path within confect/ becomes the group’s name. See File Naming Conventions and The Spec/Impl Model.

​

Rules

• Your confect/ directory should always be a sibling of your convex/ directory.
• The confect/_generated/ directory is generated by the Confect CLI. You should never modify files in this directory directly.
• Confect treats the convex directory as a codegen target. While using Confect, you should never modify files in the convex folder directly, except for tsconfig.json and convex.config.ts.