TypeScript DSL for authoring OpenAPI 3.1+ specs. Uses TypeBox for JSON Schema with full type inference — you write TypeScript, not YAML.

Docs · Playground · Getting Started · API Reference

Source mapping — TypeScript to OpenAPI YAML

import { Api, named } from '@spec-spac/spac'
import { Type } from '@sinclair/typebox'
const Pet = named('Pet', Type.Object({ id: Type.String(), name: Type.String() }))
const api = new Api('3.1', 'Petstore', { version: '1.0.0' })
api.group('/pets', g => {
  g.get('/').response(Type.Array(Pet)).summary('List all pets')
  g.post('/').body(Pet).response(Pet).summary('Create a pet')
  g.delete('/:id').params(Type.Object({ id: Type.String() })).respond(204)
})
const spec = api.emit() // valid OpenAPI 3.1 JSON

Named schemas automatically hoist to components.schemas as $refs. Groups inherit tags and security. Macros let you compose reusable route/group patterns.

Quick start

1. Install

npm install @spec-spac/spac @sinclair/typebox

2. Define your API

Create api.ts:

import { Api, named } from '@spec-spac/spac'
import { Type } from '@sinclair/typebox'
const User = named('User', Type.Object({
  id: Type.String(),
  name: Type.String(),
  email: Type.String({ format: 'email' }),
}))
const api = new Api('3.1', 'My API', { version: '1.0.0' })
api.group('/users', g => {
  g.tag('users')
  g.get('/').response(Type.Array(User)).summary('List users')
  g.get('/:id').params(Type.Object({ id: Type.String() })).response(User)
  g.post('/').body(User).response(User).summary('Create user')
})
console.log(JSON.stringify(api.emit(), null, 2))

3. Run it

npx tsx api.ts > openapi.json

That's it — openapi.json is a valid OpenAPI 3.1 document with User hoisted to components.schemas.

Packages

Package	Install	What it does
`@spec-spac/spac`	`npm i @spec-spac/spac`	Core library — define routes, groups, schemas, emit OpenAPI 3.1 JSON/YAML with source maps
`@spec-spac/from-openapi`	`npm i -g @spec-spac/from-openapi`	CLI + library — reverse-generate spac TypeScript from an existing OpenAPI spec
`@spec-spac/from-openapi-biome`	`npm i @spec-spac/from-openapi-biome`	Biome formatter plugin for the code generator
`@spec-spac/from-openapi-prettier`	`npm i @spec-spac/from-openapi-prettier`	Prettier formatter plugin for the code generator

`spac-from-openapi` CLI

Already have an OpenAPI spec? Generate spac TypeScript from it:

# Preview what will be generated (dry run)
npx @spec-spac/from-openapi petstore.json
# Generate to a directory
npx spac-from-openapi petstore.json --out ./generated
# Strip path prefixes for cleaner grouping
npx spac-from-openapi cloudflare.json --out ./generated \
  --strip '/accounts/{account_id}' \
  --strip '/zones/{zone_id}'

Flag	Description
`--out <dir>`	Output directory (omit for dry-run)
`--strip <prefix>`	Path prefix to strip before grouping (repeatable)
`--name <name>`	Override API title
`--spec-version <ver>`	Override OpenAPI version
`--debug`	Enable source map support in generated code

Output structure:

generated/
  index.ts              — Api setup, imports all groups
  shared/schemas.ts     — Schemas used by 2+ groups
  <group>/index.ts      — Routes for that group
  <group>/schemas.ts    — Schemas local to that group

Core concepts

Routes and chaining

Every HTTP method returns a builder — all configuration is chained:

api.get('/users/:id')
  .params(Type.Object({ id: Type.String() }))
  .query(Type.Object({ fields: Type.Optional(Type.String()) }))
  .response(User)
  .error(404, ErrorSchema)
  .summary('Get a user by ID')
  .operationId('getUser')
  .tag('users')

Groups

Groups collect routes under a shared prefix with inherited metadata:

api.group('/users', g => {
  g.tag('users')
  g.security('bearer')
  g.get('/').response(Type.Array(User))
  g.post('/').body(CreateUser).response(User)
  g.get('/:id').params(Type.Object({ id: Type.String() })).response(User)
})

Named schemas

Wrap any TypeBox schema with named() to hoist it to components.schemas:

const Pet = named('Pet', Type.Object({ id: Type.String(), name: Type.String() }))
// Any route referencing Pet emits { "$ref": "#/components/schemas/Pet" }

Response helpers

import { noContent, created, errorSchema } from '@spec-spac/spac'
api.post('/items')
  .body(CreateItem)
  .respond(201, created(Item))
  .respond(204, noContent())
  .error(400, errorSchema('Bad request'))

Macros

Reusable transforms applied via .use():

import { macro } from '@spec-spac/spac'
const authenticated = macro.route(r => r.security('bearer'))
const audited = macro.group(g => { g.tag('audited'); g.security('bearer') })
api.group('/admin', g => {
  g.use(audited)
  g.get('/stats').response(Stats).use(authenticated)
})

Source maps

Map every line of emitted YAML back to the TypeScript that produced it:

const api = new Api('3.1', 'Petstore', { version: '1.0.0', debug: true })
// ... define routes ...
const result = api.emit({ sourceMap: true, generatedFile: 'spec.yaml' })
result.yaml        // YAML string
result.sourceMap   // standard Source Map V3
result.sourceTable // Map<jsonPath, SourceEntry>

API reference

Method	Description
`new Api(specVersion, title, config?)`	Create a new API spec (specVersion: `'3.1'`)
`.get/.post/.put/.delete/.patch(path)`	Top-level route (returns builder for chaining)
`.group(prefix, callback)`	Group routes under a shared path prefix
`.server(config)`	Add a server
`.securityScheme(name, config)`	Register a security scheme
`.tag(config)`	Register a tag
`.security(name)`	Apply global security
`.use(macro)`	Apply an API-level macro
`.emit()`	Produce the OpenAPI 3.1 JSON document
`.emit({ yaml: true })`	Emit as YAML string
`.emit({ sourceMap: true })`	Emit YAML + Source Map V3 (requires `debug: true`)

RouteBuilder chaining

.params() .query() .headers() .body() .response() .respond() .error() .summary() .description() .tag() .operationId() .deprecated() .security() .server() .extension() .use()

Contributing

Prerequisites

Node.js 22+
pnpm 10+

Setup

git clone https://github.com/rbbydotdev/spac.git
cd spac
pnpm install

Monorepo structure

packages/
  spac/            — Core library (@spec-spac/spac)
  from-openapi/    — CLI + library for reverse-generating spac from OpenAPI
  playground/      — Interactive playground (Vite + React + CodeMirror)
  website/         — Documentation site (Next.js + Fumadocs)
  theme/           — Shared Shiki syntax themes
  spac-vscode/     — VS Code extension
  examples/        — Example projects (petstore, plantstore, serpapi, etc.)

Build & test

# Build the core library
pnpm --filter @spec-spac/spac build
# Run core tests
pnpm --filter @spec-spac/spac test
# Build + test the from-openapi package
pnpm --filter @spec-spac/from-openapi build
pnpm --filter @spec-spac/from-openapi test

Running locally

Docs site (Next.js):

pnpm --filter website dev
# → http://localhost:3000

Playground (Vite):

# Generate fixtures first (required once, or after changing examples/spac source)
pnpm --filter spac-playground generate
# Start dev server
pnpm --filter spac-playground dev

The generate step bundles type declarations, builds source maps, and creates example fixtures the playground needs. Re-run it after modifying example specs or the spac package.

Playground e2e tests

# Install browser (first time only)
pnpm exec --filter spac-playground playwright install chromium
# Run tests
pnpm --filter spac-playground test:e2e

Formatting

pnpm format        # auto-fix with Biome
pnpm format:check  # check only (used in CI)

License

MIT