# seampact

> seampact turns one YAML contract into the server code, the typed clients and the OpenAPI document of an HTTP API, for NestJS, Express, Fastify, Hono, AdonisJS, Spring Boot, Laravel, Symfony, FastAPI, Django REST Framework and Django Ninja. You write the handlers; the generated code checks every request and reply.

- Change the API in the contract (`contract/*.yaml`), never in the generated folder (`outDir` in `seampact.config.yaml`).
- After each change run generate, then check, then the compiler of your language; the command differs per stack, see Commands per stack.
- Every error starts with a code and ends with `Fix:`: apply it, and find the code's prefix under Troubleshooting.

Start with the stack file of your server or clients: one file holds the commands, the contract essentials, the guide, the validators and the error tables of that stack. Every other link is the raw Markdown of one page; read the page your task needs.

## Stack files
- [NestJS](https://jubasse.github.io/seampact/llms-nestjs.txt): Node server
- [Express](https://jubasse.github.io/seampact/llms-express.txt): Node server
- [Fastify](https://jubasse.github.io/seampact/llms-fastify.txt): Node server
- [Hono](https://jubasse.github.io/seampact/llms-hono.txt): Node server
- [AdonisJS](https://jubasse.github.io/seampact/llms-adonisjs.txt): Node server
- [Spring Boot](https://jubasse.github.io/seampact/llms-spring-boot.txt): Java and Kotlin server
- [Laravel](https://jubasse.github.io/seampact/llms-laravel.txt): PHP server
- [Symfony](https://jubasse.github.io/seampact/llms-symfony.txt): PHP server
- [FastAPI](https://jubasse.github.io/seampact/llms-fastapi.txt): Python server
- [Django REST Framework](https://jubasse.github.io/seampact/llms-drf.txt): Python server
- [Django Ninja](https://jubasse.github.io/seampact/llms-ninja.txt): Python server
- [Clients](https://jubasse.github.io/seampact/llms-clients.txt): Typed TypeScript clients

## Introduction
- [What is seampact](https://jubasse.github.io/seampact/md/concepts/what-is-seampact.md): what it does, in two paragraphs.
- [What you get and what you write](https://jubasse.github.io/seampact/md/concepts/what-you-get.md): what seampact generates, what is yours and what it does not do.
- [Supported versions](https://jubasse.github.io/seampact/md/supported-versions.md): every framework and its versions.
- [Glossary](https://jubasse.github.io/seampact/md/concepts/glossary.md): the words these docs use, one meaning each.
- [Packages](https://jubasse.github.io/seampact/md/concepts/packages.md): the package map.

## Getting started
- [Install](https://jubasse.github.io/seampact/md/getting-started/01-install.md): install seampact from npm and start a project.
- [Your first API](https://jubasse.github.io/seampact/md/getting-started/your-first-api.md): a notes API on the server of your choice, step by step.
- [Call it from React](https://jubasse.github.io/seampact/md/getting-started/call-it-from-react.md): a typed client and hooks.
- [Check it in CI](https://jubasse.github.io/seampact/md/features/check-in-ci.md): fail the build on drift.
- [Add to an existing app](https://jubasse.github.io/seampact/md/getting-started/04-existing-project.md): move routes one at a time.
- [Project layout](https://jubasse.github.io/seampact/md/getting-started/05-project-layout.md): what each file is.
- [Work with an AI agent](https://jubasse.github.io/seampact/md/getting-started/06-ai-agents.md): guard rails for an agent.
- [Install in other ecosystems](https://jubasse.github.io/seampact/md/getting-started/install-other-ecosystems.md): Maven Central, Packagist, PyPI, the binary and a checkout.

## Writing the contract
- [The shape of a contract](https://jubasse.github.io/seampact/md/contract/01-basics.md): api, surfaces, collections and routes.
- [Types and references](https://jubasse.github.io/seampact/md/contract/02-types-and-refs.md): schemas, enums, split files.
- [Errors](https://jubasse.github.io/seampact/md/contract/03-errors.md): declare, attach and rename codes.
- [Access](https://jubasse.github.io/seampact/md/contract/04-access.md): public routes, identities and rights.
- [Lists](https://jubasse.github.io/seampact/md/contract/05-lists.md): paging styles and sorting.
- [Versioning and change](https://jubasse.github.io/seampact/md/contract/06-versioning.md): version, maturity, deprecation.
- [Advanced](https://jubasse.github.io/seampact/md/contract/07-advanced.md): uploads, lost updates, cache.

## Types and validation
- [Types and validation](https://jubasse.github.io/seampact/md/types-and-validation/README.md): what each stack gets from your schemas, the 400 error body and the rules modes.
- [TypeScript types](https://jubasse.github.io/seampact/md/types-and-validation/typescript-types.md): one type per schema, request, reply and error.
- [zod](https://jubasse.github.io/seampact/md/types-and-validation/zod.md): zod schemas for the Node servers.
- [yup](https://jubasse.github.io/seampact/md/types-and-validation/yup.md): yup schemas for the Node servers.
- [class-validator](https://jubasse.github.io/seampact/md/types-and-validation/class-validator.md): decorated DTO classes for NestJS.
- [Ajv](https://jubasse.github.io/seampact/md/types-and-validation/ajv.md): Fastify's own validators, when you link none.
- [VineJS](https://jubasse.github.io/seampact/md/types-and-validation/vinejs.md): AdonisJS's own validators, when you link none.
- [Java records](https://jubasse.github.io/seampact/md/types-and-validation/java-records.md): records and a generated structural validator on Spring Boot.
- [Laravel rules](https://jubasse.github.io/seampact/md/types-and-validation/laravel-rules.md): FormRequest rules on Laravel.
- [Symfony constraints](https://jubasse.github.io/seampact/md/types-and-validation/symfony-constraints.md): classes and constraints on Symfony.
- [Pydantic](https://jubasse.github.io/seampact/md/types-and-validation/pydantic.md): Pydantic 2 models on FastAPI and Django Ninja.
- [DRF serializers](https://jubasse.github.io/seampact/md/types-and-validation/drf-serializers.md): dataclasses and serializers on Django REST Framework.

## Server guides
- [NestJS](https://jubasse.github.io/seampact/md/backend/nestjs.md): Node, decorators and a module.
- [Express](https://jubasse.github.io/seampact/md/backend/express.md): Node, Express 4 and 5.
- [Fastify](https://jubasse.github.io/seampact/md/backend/fastify.md): Node, Fastify 5 with route hooks.
- [AdonisJS](https://jubasse.github.io/seampact/md/backend/adonisjs.md): Node, AdonisJS 7 and 6.
- [Hono](https://jubasse.github.io/seampact/md/backend/hono.md): Hono 4 on any Web-standard runtime.
- [Access hooks on Node](https://jubasse.github.io/seampact/md/backend/node-hooks.md): authenticate, decide and resolve scope on the five Node servers.
- [Spring Boot](https://jubasse.github.io/seampact/md/backend/spring-boot.md): Java, the Gradle or Maven plugin, controllers and hooks.
- [Laravel](https://jubasse.github.io/seampact/md/backend/laravel.md): PHP, Composer, controllers, hooks and Laravel's own auth.
- [Symfony](https://jubasse.github.io/seampact/md/backend/symfony.md): PHP, the Composer package, bundle, controllers, hooks and SecurityBundle.
- [FastAPI](https://jubasse.github.io/seampact/md/backend/fastapi.md): Python, the wheels, bind_<api>(), handlers, hooks and FastAPI's own docs.
- [Django REST Framework](https://jubasse.github.io/seampact/md/backend/drf.md): Python, the wheels, settings, URLconf, handlers, hooks and DRF's own auth.
- [Django Ninja](https://jubasse.github.io/seampact/md/backend/ninja.md): Python, the wheels, bind_<api>(), handlers, hooks, Ninja's own auth and docs.

## Client guides
- [Fetch client](https://jubasse.github.io/seampact/md/frontend/fetch-client.md): the typed fetch client every other client builds on.
- [React](https://jubasse.github.io/seampact/md/frontend/react.md): TanStack Query, SWR or RTK Query hooks over the fetch client.
- [Vue](https://jubasse.github.io/seampact/md/frontend/vue.md): TanStack Query, Pinia Colada or plain fetch composables.
- [Angular](https://jubasse.github.io/seampact/md/frontend/angular.md): an HttpClient service with signals, NgRx optional.
- [MSW mocks](https://jubasse.github.io/seampact/md/frontend/msw.md): typed mock handlers to test the client with no backend.
- [Point the client at your backend](https://jubasse.github.io/seampact/md/frontend/backend-url.md): the backend URL per environment, Docker included.
- [Expo and React Native](https://jubasse.github.io/seampact/md/frontend/mobile.md): the client and the React hooks on a phone.

## Workflow
- [Commands per stack](https://jubasse.github.io/seampact/md/features/commands-per-stack.md): how to run each command on Node, Gradle, Maven, PHP and Python.
- [Diff](https://jubasse.github.io/seampact/md/features/diff.md): see what a contract edit breaks.
- [Sharing contracts](https://jubasse.github.io/seampact/md/features/sharing-contracts.md): publish a contract to other repositories.
- [Lint](https://jubasse.github.io/seampact/md/features/lint.md): run lint, change a rule level, allow a case.
- [Convention packs](https://jubasse.github.io/seampact/md/features/convention-packs.md): add a pack, what each brings.
- [Editor support](https://jubasse.github.io/seampact/md/features/editor-support.md): checks and completion in your editor.

## Configuration
- [The config file](https://jubasse.github.io/seampact/md/configuration/config-file.md): location, output folder, sources.
- [Targets and links](https://jubasse.github.io/seampact/md/configuration/targets-and-links.md): add a target, which generators combine.
- [Switch the validator](https://jubasse.github.io/seampact/md/configuration/validators.md): change the validator library, or the rules mode.
- [OpenAPI and docs](https://jubasse.github.io/seampact/md/configuration/openapi-and-docs.md): OpenAPI documents and Swagger.
- [Monorepo](https://jubasse.github.io/seampact/md/configuration/monorepo.md): one config for several apps.
- [Config reference](https://jubasse.github.io/seampact/md/configuration/reference.md): every key, its type and default.

## Troubleshooting
- [Troubleshooting](https://jubasse.github.io/seampact/md/troubleshooting/README.md): find an error by its code.
- [Config errors](https://jubasse.github.io/seampact/md/troubleshooting/config.md): config.*.
- [Monorepo and OpenAPI errors](https://jubasse.github.io/seampact/md/troubleshooting/config-root.md): config.root.*, config.apps.*, config.openapi.*.
- [Link errors](https://jubasse.github.io/seampact/md/troubleshooting/link.md): link.*.
- [Bundle errors](https://jubasse.github.io/seampact/md/troubleshooting/bundle.md): bundle.*.
- [Target option errors](https://jubasse.github.io/seampact/md/troubleshooting/generate.md): options.*, paging.*.
- [Check errors](https://jubasse.github.io/seampact/md/troubleshooting/check.md): check.*, writer.*.
- [Contract file errors](https://jubasse.github.io/seampact/md/troubleshooting/load.md): seampact/load/*.
- [Contract key errors](https://jubasse.github.io/seampact/md/troubleshooting/validate.md): seampact/validate/*.
- [Contract content errors](https://jubasse.github.io/seampact/md/troubleshooting/tree.md): seampact/tree/*.
- [Access and error code errors](https://jubasse.github.io/seampact/md/troubleshooting/access-and-errors.md): seampact/access/*, seampact/derive/*.
- [Signed webhook errors](https://jubasse.github.io/seampact/md/troubleshooting/signed-webhooks.md): signature.*.
- [Boot errors](https://jubasse.github.io/seampact/md/troubleshooting/boot.md): the server refuses to start.
- [CLI errors](https://jubasse.github.io/seampact/md/troubleshooting/cli.md): cli.*, init.*, compile.*, ir.*, lint.*, diff.*, explain.*, binary.*, bundle.source.*.

## Reference
- [Grammar](https://jubasse.github.io/seampact/md/grammar/index.md): every contract key, section by section (full example).

## Release notes
- [1.0.1](https://jubasse.github.io/seampact/md/release-notes/1.0.1.md): server fixes, clearer errors, docs and agent skills.
- [1.0.0](https://jubasse.github.io/seampact/md/release-notes/1.0.0.md): the first release.

## Optional
- [All user pages in one file](https://jubasse.github.io/seampact/llms-full.txt): every user page.