Project Structure

​

confect/

​

_generated/

​

components.ts

Contains a typed components registry with one entry per Convex component installed via app.use(...) in convex/convex.config.ts. Use it wherever a component client expects a component reference (e.g. new Workpool(components.workpool, ...)). Unlike the components export of convex/_generated/api, this file is safe to import from your impl files’ import graphs. See Components.

​

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.

​

docs.ts

Contains a named TypeScript interface for each table’s document—NotesDoc, UsersDoc, etc.—plus a Docs registry mapping each table name to its interface. These are pure types (no runtime code): use them to annotate a value with a table’s document type, e.g. const note: NotesDoc = …. The Docs registry is what lets the DatabaseReader/DatabaseWriter services hand documents back under their named types. See Document types.

​

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 fields or 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 or Doc 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. These wrappers are client-safe: they do not import @confect/server, so a spec that uses notes.Doc can ship in _generated/refs.ts without pulling the server package into the browser.

​

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 HttpRouter.make and Effect’s effect/unstable/http/effect/unstable/httpapi 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(...) from @confect/core); 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.

​

middleware/

Optional Defines your middleware, as a <Name>.spec.ts/<Name>.impl.ts pair per middleware. Like tables/, this directory name is reserved: Confect does not scan it for function groups, so its spec/impl pairs declare and implement middleware rather than a group, and no convex/ module is emitted for them. Middleware is shared across groups, which is why it lives here rather than inside any one group’s spec.

​

*.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.
• Spec modules are bundled into your client, so nothing a *.spec.ts reaches may value-import @confect/server (tables/ and _generated/ excepted, since a Table needs it); use import type when you only need the types. confect codegen enforces this.
• 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.