Convex Schema Generator

Generate the root Convex schema from convex/**/schema.ts. Each submodule schema defines its own tables, and the generated convex/schema.gen.ts imports those schemas and groups their tables by first-level folder.

Use it in a Convex project

In your Convex project, install the generator and its peer dependency:

pnpm add convex convex-helpers
pnpm add -D @esauflores/convex-schema-generator

The npm package is scoped, but its executable is convex-schema-generator.

Keep convex/schema.ts as the Convex schema entry point. The generator creates it to re-export schema.gen.ts when it is missing. Create a schema in a submodule and export a defineSchema result as the default export. For example, convex/admin/users/schema.ts can contain:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  users: defineTable({
    name: v.string(),
    email: v.string(),
  }),
});

Run the generator from your Convex project when you add, remove, or move a schema file:

pnpm exec convex-schema-generator generate

The command writes convex/schema.gen.ts and creates convex/schema.ts when it is missing. Run it again after changing the schema folder structure, then run convex dev or convex deploy as usual. The CLI requires Node 20 or newer.

Schemas are grouped by their first-level folder. For example, convex/admin/users/schema.ts and convex/admin/projects/schema.ts are emitted under the admin schema section in the root file:

// admin schema
...usersSchema.tables,
...projectsSchema.tables,

Schemas directly inside a first-level folder are supported as well, such as convex/public/schema.ts. The generator ignores the root convex/schema.ts, convex/schema.gen.ts, and all _generated folders.

Table names must be unique across all schema files. Duplicate table names emit a warning and must be corrected before deploying.

Run the example

The included convex/ project provides:

• Admin tables for users, projects, tasks, comments, and tags.
• A public posts table.
• CRUD data modules backed by the per-resource schemas.
• A generated root schema grouped into admin and public sections.

For this repository, generate the example schema and start the local Convex backend in one terminal:

pnpm convex:generate
pnpm convex:dev

Run the generator tests in another terminal:

pnpm test

pnpm test checks schema discovery, grouping, duplicate-name warnings, regeneration, and ignored folders without requiring a Convex backend.