convex-typegen

Rust types from your Convex schema.ts and function modules. Runs in build.rs so generated code stays in sync with your backend.

Docs: docs.rs/convex-typegen

Setup

Add the crate (library + build script):

cargo add convex-typegen
cargo add --build convex-typegen

Add build.rs:

use convex_typegen::prelude::*;

fn main() {
    let config = Configuration::default();

    println!("cargo:rerun-if-changed={}", config.schema_path.display());
    println!("cargo:rerun-if-changed={}", config.convex_dir.display());
    for path in rcfp(&config).expect("resolve convex function sources") {
        println!("cargo:rerun-if-changed={}", path.display());
    }

    if let Err(e) = generate(config) {
        panic!("convex-typegen failed: {e}");
    }
}

cargo build writes the generated file (see defaults below). Include it in your crate (mod convex_types; or whatever matches out_file) and pull in convex_typegen::prelude::* where you call Convex with the generated arg types.

A full minimal setup lives in examples/basic in this repo.

Generated names

Function argument structs are named {Module}{Export}Args when the export does not already start with the module file name (without .ts). Examples:

Module file	Export	Generated struct
`games.ts`	`getGame`	`GamesGetGameArgs`
`mod_a.ts`	`list`	`ModAListArgs`
`tasks.ts`	`tasksSearch`	`TasksSearchArgs`

FUNCTION_PATH strings are unchanged (e.g. "games:getGame").

Nested v.object({ ... }) validators emit their own pub struct (nesting depth under 8). Empty objects and deeper nesting still fall back to ConvexJsonValue.

Source	Example	Generated struct
Schema column	`projects.settings`	`ProjectsSettings`
Function arg object	`integrations.ts` `integrationsMirror` arg `flags`	`IntegrationsMirrorFlags`
Nested object field	parent `ProjectsSettings` + field `theme`	`ProjectsSettingsTheme`
Array of objects	column `items` whose elements are objects	`{Table}{Column}Element`

Identical shapes under the same name are reused; conflicting shapes under the same name fail codegen with InvalidSchema.

Defaults

Field	Default
`schema_path`	`convex/schema.ts`
`out_file`	`src/convex_types.rs`
`convex_dir`	`convex`

Paths are relative to the package directory when Cargo runs the build script.

Function sources: every *.ts under convex_dir, except the schema file, _generated/, node_modules/, and *.d.ts. Set function_paths to a non-empty list to skip discovery and pass files explicitly.

Features

Feature	Default	Description
`client`	on	Re-exports `ConvexClientExt`, `IntoConvexValue`, `ConvexValueExt` (pulls in the `convex` crate).
`verbose`	off	Print Oxc diagnostics to stderr during parse failures.

Build-only usage (smaller dependency tree):

[build-dependencies]
convex-typegen = { version = "0.4", default-features = false }

Serde

Generated code pulls serde and serde_json through convex-typegen, so a minimal app crate does not need those as direct dependencies unless you use them yourself.

Versioning

Semantic versioning policy — library API vs generated output, MSRV, and release rules.
API stability reference — stable vs unstable public items.

Pin the same crate version in [dependencies] and [build-dependencies]. On 0.x, breaking codegen may ship in a minor (this crate, 0.4.0). From 1.0, generated type renames require a major bump.

License

MIT — see LICENSE.

convex-typegen 0.4.0