Support matrix

This page answers two practical questions: what convex-typegen can generate from your project today, and what to do when static analysis is not enough.

Rust versions

CI checks each crate at its declared MSRV.

What you can generate offline

The generator reads convex/schema.ts for tables and either:

1. TypeScript under your Convex root — exported public queries, mutations, and actions whose validators are visible to the offline resolver, or
2. A committed function-spec JSON file — the public function list and resolved validators from a deployment you captured with the Convex CLI.

Start with TypeScript. When a function builds validators at runtime, spreads from unknown sources, or uses patterns the resolver skips, generation fails with a file path and span when possible. That is your signal to generate and commit a function spec instead of guessing types.

Supported Convex validators

These match Convex 1.49-style validator types:

The schema parser accepts required object tables and unions of required object shapes, including .index(), .searchIndex(), and .vectorIndex() chains. Unsupported validator calls, dynamic record keys, or invalid record key types fail loudly during generation.

Raw values and undeclared validators

When an endpoint omits an args or return validator, codegen still emits a reference—you pass or receive RawArgs / RawValue instead of a typed struct. Declared empty args {} still get a dedicated empty struct.

Committing a function spec is the supported way to get typed args and returns for functions whose TypeScript cannot be analyzed fully offline.

TypeScript the offline parser understands

By default the tool scans .ts files under convex_dir, skipping the resolved schema file, _generated/, node_modules/, declaration files, http.ts, crons.ts, and convex.config.ts. You can replace discovery with an explicit file list in Configuration::function_paths.

Supported patterns include:

• Exported const endpoints calling query, mutation, action, or their internal* variants imported from convex/server or /_generated/server.
• Inline validators, same-file const aliases, and named validators imported from relative modules (including sibling constants in the imported file).
• Static object spreads that resolve to object literals.
• TypeScript as / satisfies wrappers around validators—they are peeled off.

Not supported: validators built at runtime, cyclic imports, most dynamic spreads, and unsupported export or import forms.

Function discovery and generated module names are based on files under the configured Convex root. Explicit function_paths do not make files outside that root eligible for generated API references.

Reference: resolver limits

To keep generation predictable, validator following and object-spread inlining stop at depth 64. Beyond that, or when an expression is not one of the supported forms above, use a committed function spec captured from a backend that already resolved the validators.

A function spec replaces TypeScript function discovery entirely but does not replace schema.ts—table definitions still come from your schema file.

What appears under api

Only public queries, mutations, and actions become api references. Internal functions, HTTP routes in http.ts, and crons in crons.ts are skipped. Folder layout mirrors Convex modules. See path-scoped names.