Code & Spec Generators

Generate OpenAPI 3.1 specifications and typed client contracts from application code.

The brick gen command extracts OpenAPI 3.1 specifications and typed browser client contracts directly from application code.

Generating OpenAPI 3.1 (`brick gen openapi`)

Extract the complete OpenAPI 3.1 specification from your application entry:

# Print specification JSON to stdout:
brick gen openapi src/server.ts

# Write specification JSON to a file:
brick gen openapi src/server.ts --output openapi.json

Output:

✅ OpenAPI 3.1 specification written to openapi.json

How It Works

brick gen openapi loads your application entry file (which must default-export a BrickApp instance), inspects all registered services, mounts, and CRUD access policies, and calls generateOpenApiSpec() from @brickkit/core.

Generating Typed Client Contracts (`brick gen client`)

Generate a standalone TypeScript client contract file for browser frontends without running Vite or launching an HTTP server:

# Generate default contract in _brick/contract.ts:
brick gen client src/server.ts

# Write contract to a custom destination:
brick gen client src/server.ts --output src/client/contract.ts

Output (the CLI prints the absolute resolved path):

Client contract written to /Users/project/src/client/contract.ts

Generated Contract Structure

The generated contract file contains TypeScript types and route metadata used by createBrickClient and the TanStack Query client:

src/client/contract.ts

// Generated by the Brick Vite plugin. Do not edit.
import type { BrickClientAction } from "@brickkit/core/client";

export type AppContract = {
  pages: {
    page: {
      list: BrickClientAction<PageQueryInput, PageListOutput>;
      get: BrickClientAction<{ id: string }, PageOutput>;
      create: BrickClientAction<PageCreateInput, PageOutput>;
    };
  };
};

export const contract: AppContract = JSON.parse("...");

Frontend applications import this contract to provide autocompletion and compile-time validation:

src/frontend/api.ts

import { createBrickClient } from "@brickkit/core/client";
import { contract } from "../client/contract";

export const api = createBrickClient({
  baseUrl: "http://localhost:4000",
  contract,
});

Options Summary

Subcommand	Flag	Description
`openapi`	`<entry>`	(Required) Application entry file default-exporting a `BrickApp`.
`openapi`	`--output <file>`	Writes JSON to specified file path instead of stdout.
`client`	`<entry>`	(Required) Application entry file default-exporting a `BrickApp`.
`client`	`--output <file>`	Destination file path (defaults to `_brick/contract.ts`).

Run generation during development and builds

For Vite 8, use the automatic contract plugin. It runs before frontend startup and production compilation and regenerates after API edits.

For other frontend tools, use brick dev --client --frontend. Put brick gen client first in production build and typecheck scripts so a clean checkout has the contract before frontend compilation.

All integrations share the same generator and atomic writer. Unchanged content preserves the destination file and its timestamp. Generation errors preserve the previous contract. The entry must default-export a BrickApp without calling .listen(); keep startup side effects in a separate bootstrap.

Code & Spec Generators

Generating OpenAPI 3.1 (brick gen openapi)Copy Anchor Link

How It WorksCopy Anchor Link

Generating Typed Client Contracts (brick gen client)Copy Anchor Link

Generated Contract StructureCopy Anchor Link

Options SummaryCopy Anchor Link

Run generation during development and buildsCopy Anchor Link