Configuration and CLI
Both the Cargo helpers and the CLI read local inputs and generate the same Rust code. Use the CLI for explicit generation or drift checks. Use a Cargo helper to regenerate automatically when the consumer’s inputs change.
Rust configuration
Start with convex_typegen::config::Configuration::default() and use the setters to
override fields. The struct is non-exhaustive. The setters accept paths convertible to
PathBuf except with_function_paths, which takes a Vec<PathBuf>.
| Setting | Default and effect |
|---|---|
convex_dir: PathBufwith_convex_dir | convex. Root for source discovery, module names, and the default schema path. |
schema_path: Option<PathBuf>with_schema_path | None. Use <convex_dir>/schema.ts. An explicit override is resolved independently of convex_dir. |
function_paths: Vec<PathBuf>with_function_paths | Empty. Discover functions under the Convex root. A non-empty list replaces discovery unless a spec is configured. Files outside the root do not produce public references. |
function_spec_path: Option<PathBuf>with_function_spec_path | None. When set, use this JSON file as the complete function inventory and ignore function_paths. The schema is still read from TypeScript. |
out_file: PathBufwith_out_file | $OUT_DIR/convex_api.rs if the environment variable is set; otherwise the relative path OUT_DIR/convex_api.rs. The CLI requires an explicit output when the variable is unset. |
Relative paths resolve from the current working directory: the consumer package root
in Cargo’s build script, and the directory from which you invoke the CLI. Only the implicit
schema path is joined to convex_dir. For example, from apps/desktop,
--convex-dir ../backend/convex --schema overrides/schema.ts reads
apps/desktop/overrides/schema.ts and discovers modules under apps/backend/convex.
config.resolved_schema_path() returns the selected schema path before filesystem resolution.
Cargo helpers and rerun tracking
convex_typegen::build::generate_out_dir()uses the default layout and requires Cargo’sOUT_DIR. It writesconvex_api.rsthere.convex_typegen::build::generate(config)accepts a custom configuration. See the monorepo example.- Both helpers emit
cargo:rerun-if-changedfor the schema and loaded relative imports, plus the selected spec or TypeScript function files and their loaded imports. Discovery also watches the Convex directory for added or removed modules. - The crate-root
convex_typegen::generate(config)writes bindings without Cargo directives. The crate-rootconvex_typegen::check(config)reports whether output is current without writing. TheverboseCargo feature prints additional parser and semantic diagnostics.
CLI
convex-typegen [--check] [--schema PATH] [--convex-dir PATH] [--output PATH]
[--function-spec PATH] [--function PATH]
| Flag | Behavior |
|---|---|
--convex-dir PATH | Set the Convex root; defaults to convex. |
--schema PATH | Override the schema; defaults to <convex-dir>/schema.ts. |
--function PATH | Parse this explicit function source. Repeat for each source. With none, discover files. |
--function-spec PATH | Read an authoritative spec. Takes precedence over every --function value. |
--output PATH | Set the output file. Required unless OUT_DIR is set, in which case the default is $OUT_DIR/convex_api.rs. |
--check | Off by default. Compare generated bytes with the existing output without modifying it. |
--help, -h | Print usage and exit. |
Repeated single-path flags use the last value. Pass flags and paths as separate arguments. Exit status 0 means success (including current output in check mode), 1 means check mode found missing or stale output, and 2 means an invalid invocation or generation error.
For example, to check a committed output against a spec in a neighboring package:
convex-typegen --check --convex-dir ../backend/convex \
--function-spec ../backend/function-spec.json --output src/convex_api.rs