Documentation

seampact turns one YAML contract into the server code, the typed clients and the OpenAPI document of your HTTP API. You write the handlers. seampact writes the checks around them, and seampact check fails in CI when the generated files drift from the contract.

The same pages, with search, are on the documentation site. New here? Read What is seampact, then Install.

Introduction

• What is seampact: what it does, in two paragraphs.
• What you get and what you write: what seampact generates, what is yours and what it does not do.
• Supported versions: every framework and its versions.
• Glossary: the words these docs use, one meaning each.
• Packages: the package map.

Getting started

• Install: install seampact from npm and start a project.
• Your first API: a notes API on the server of your choice, step by step.
• Call it from React: a typed client and hooks.
• Check it in CI: fail the build on drift.
• Add to an existing app: move routes one at a time.
• Project layout: what each file is.
• Work with an AI agent: guard rails for an agent.
• Install in other ecosystems: Maven Central, Packagist, PyPI, the binary and a checkout.

Writing the contract

• Contract: how to write the contract, one task per page.
• The shape of a contract: api, surfaces, collections and routes.
• Types and references: schemas, enums, split files.
• Errors: declare, attach and rename codes.
• Access: public routes, identities and rights.
• Lists: paging styles and sorting.
• Versioning and change: version, maturity, deprecation.
• Advanced: uploads, lost updates, cache.

Types and validation

• Types and validation: what each stack gets from your schemas, the 400 error body and the rules modes.
• TypeScript types: one type per schema, request, reply and error.
• zod: zod schemas for the Node servers.
• yup: yup schemas for the Node servers.
• class-validator: decorated DTO classes for NestJS.
• Ajv: Fastify’s own validators, when you link none.
• VineJS: AdonisJS’s own validators, when you link none.
• Java records: records and a generated structural validator on Spring Boot.
• Laravel rules: FormRequest rules on Laravel.
• Symfony constraints: classes and constraints on Symfony.
• Pydantic: Pydantic 2 models on FastAPI and Django Ninja.
• DRF serializers: dataclasses and serializers on Django REST Framework.

Server guides

• NestJS: Node, decorators and a module.
• Express: Node, Express 4 and 5.
• Fastify: Node, Fastify 5 with route hooks.
• AdonisJS: Node, AdonisJS 7 and 6.
• Hono: Hono 4 on any Web-standard runtime.
• Access hooks on Node: authenticate, decide and resolve scope on the five Node servers.
• Spring Boot: Java, the Gradle or Maven plugin, controllers and hooks.
• Laravel: PHP, Composer, controllers, hooks and Laravel’s own auth.
• Symfony: PHP, the Composer package, bundle, controllers, hooks and SecurityBundle.
• FastAPI: Python, the wheels, bind_<api>(), handlers, hooks and FastAPI’s own docs.
• Django REST Framework: Python, the wheels, settings, URLconf, handlers, hooks and DRF’s own auth.
• Django Ninja: Python, the wheels, bind_<api>(), handlers, hooks, Ninja’s own auth and docs.

Client guides

• Fetch client: the typed fetch client every other client builds on.
• React: TanStack Query, SWR or RTK Query hooks over the fetch client.
• Vue: TanStack Query, Pinia Colada or plain fetch composables.
• Angular: an HttpClient service with signals, NgRx optional.
• MSW mocks: typed mock handlers to test the client with no backend.
• Point the client at your backend: the backend URL per environment, Docker included.
• Expo and React Native: the client and the React hooks on a phone.

Workflow

• Commands per stack: how to run each command on Node, Gradle, Maven, PHP and Python.
• Diff: see what a contract edit breaks.
• Check in CI: fail the build on drift.
• Sharing contracts: publish a contract to other repositories.
• Lint: run lint, change a rule level, allow a case.
• Convention packs: add a pack, what each brings.
• Editor support: checks and completion in your editor.

Configuration

• The config file: location, output folder, sources.
• Targets and links: add a target, which generators combine.
• Switch the validator: change the validator library, or the rules mode.
• OpenAPI and docs: OpenAPI documents and Swagger.
• Checks: what check fails on; the levels are set in Check in CI.
• Monorepo: one config for several apps.
• Config reference: every key, its type and default.

Troubleshooting

• Troubleshooting: find an error by its code.
• Config errors: config.*.
• Monorepo and OpenAPI errors: config.root.*, config.apps.*, config.openapi.*.
• Link errors: link.*.
• Bundle errors: bundle.*.
• Target option errors: options.*, paging.*.
• Check errors: check.*, writer.*.
• Contract file errors: seampact/load/*.
• Contract key errors: seampact/validate/*.
• Contract content errors: seampact/tree/*.
• Access and error code errors: seampact/access/*, seampact/derive/*.
• Signed webhook errors: signature.*.
• Boot errors: the server refuses to start.
• CLI errors: cli.*, init.*, compile.*, ir.*, lint.*, diff.*, explain.*, binary.*, bundle.source.*.

Reference

• Grammar: every contract key, section by section (full example).
• Supported versions: which framework versions seampact supports, and when it drops one.

Release notes

• Release notes: what each release ships and its known limits.
• 1.0.1: server fixes, clearer errors, docs and agent skills.
• 1.0.0: the first release.

Design

For contributors. Users do not need these pages.

• IR: the compiled form of a contract.
• ADRs: design records.
• Product decisions: the log of decisions, A1 to A48.
• Design decisions
• Roadmap