dartvex_codegen

CLI code generator for Convex backends. Generates type-safe Dart bindings from your Convex schema and function spec — companion tool to dartvex.

The Dartvex ecosystem

Package	Description
`dartvex`	Core client — WebSocket sync, subscriptions, auth
`dartvex_flutter`	Flutter widgets — Provider, Query, Mutation
`dartvex_codegen`	CLI code generator — type-safe Dart bindings from schema
`dartvex_local`	Offline support — SQLite cache, mutation queue
`dartvex_auth_better`	Better Auth adapter

Source and full docs: github.com/AndreFrelicot/dartvex

Installation

dev_dependencies:
  dartvex_codegen: ^0.2.0

Requires Dart ^3.7.0.

The generated bindings call APIs introduced in dartvex 0.2.0 (such as ConvexFunctionCaller.paginatedQuery and QueryLoading), so the application consuming the generated code needs:

dependencies:
  dartvex: ^0.2.0

Usage

Generate from an existing Convex TypeScript project:

dart run dartvex_codegen generate \
  --project /path/to/convex-backend \
  --output /path/to/dart_app/lib/convex_api

Generate from a previously exported spec file:

dart run dartvex_codegen generate \
  --spec-file /path/to/function_spec.json \
  --output /path/to/dart_app/lib/convex_api

Useful flags:

--client-import package:dartvex/dartvex.dart
--dry-run
--verbose
--watch

Before committing an exported spec file, scrub the real deployment URL it bakes in:

npx convex function-spec | dart run dartvex_codegen scrub > function_spec.json

scrub reads from stdin (or --spec-file) and writes the spec with the top-level url replaced by https://your-deployment.convex.cloud (customizable via --placeholder-url). The transform is idempotent and preserves key order, so committed diffs stay minimal.

Generated API

The generator produces:

api.dart as the main entrypoint
runtime.dart with shared helper types like Optional<T>
schema.dart with typed table IDs
modules/... with typed wrappers around Convex queries, mutations, and actions

Example:

import 'package:dartvex/dartvex.dart';
import 'package:my_app/convex_api/api.dart';

final client = ConvexClient('https://your-deployment.convex.cloud');
final api = ConvexApi(client);

final messages = await api.messages.list();
await api.messages.send(author: 'Andre', text: 'Hello');
final subscription = api.messages.listSubscribe();

How It Works

The public Dart API is the CLI entrypoint (GenerateCommand / runConvexCodegen); the stages below are internal:

Stage	Description
`GenerateCommand`	Main CLI command for code generation
`SpecParser`	Parses Convex function_spec.json
`TypeMapper`	Maps Convex types to Dart types
`DartGenerator`	Generates Dart source from function specs
`FileEmitter`	Writes generated files to disk

Workflow

Keep your Convex backend in TypeScript.
Run dartvex_codegen generate.
Import the generated api.dart in your Dart or Flutter app.
Call typed wrappers instead of raw function names and raw maps.

Full Documentation

See the Dartvex monorepo for full documentation and examples.