shared-types

Files (2)

• SKILL.md
• generators.md · references/

SKILL.md (first lines)

# Shared types

These rules apply when a repository has a Rust backend and a TypeScript or
JavaScript frontend that exchange data. The repository's `AGENTS.md` names
the generator, the regenerate command, the generated directory, and the
wire form of large numbers and dates.
[references/generators.md](references/generators.md) holds the setup and
the commands for each generator.

## One source

- Rust owns every type that crosses the boundary: request and response
  bodies, query parameters, events, messages, and error payloads.
- The frontend never hand-writes a type, interface, or data transfer
  object for backend data. It imports the generated type.
- The generator reads the serde attributes, so the wire format and the
  TypeScript type come from one definition. Keep the attributes on the
  Rust type.
- A type that the generator cannot express is a design problem on the Rust
  side. Change the Rust type. Do not patch the TypeScript.
- Boundary types live in one crate, the `-interface` or `-api` crate that
  the `rust` skill describes, so that one command generates all of them.

## Generators

- For an HTTP API, derive the OpenAPI document from the Rust types with
  `utoipa`, and generate the TypeScript types from that document with
  `openapi-typescript`. The frontend gets the paths and the schemas, and
  the document doubles as the API reference.
- For every other boundary, for example RPC, WebSocket messages, or types
  that a desktop shell shares, export the TypeScript types with `ts-rs`.
- A repository can name a different generator in `AGENTS.md` when it has a
  reason, for example a WebAssembly boundary. The rule does not change:
  Rust is the source, and the frontend consumes generated output.

## Shapes

- Prefer shapes that the generator expresses exactly: structs, internally
  tagged enums for discriminated unions, string-keyed maps, and `Option`
  for a value that can be null or absent.
- Do not use `serde_json::Value` or other untyped JSON in a boundary type.
  See the `rust` skill.
- Decide the wire form of 64-bit integers, decimals, and dates once per
  repository, and record it in `AGENTS.md`. A string is the usual choice
  when JavaScript number precision is not enough.

## Output

- One command regenerates every generated file. `AGENTS.md` names it under
  `## Commands`.
- Generated files live in one directory that `AGENTS.md` names, and each
  file starts with the generator's header. Never hand-edit a generated
  file. Run the command instead.
- Commit the generated files. The frontend then builds without a Rust
  toolchain, and the review diff shows every contract change.
- The repository gate regenerates the files and fails on a diff, once the
  user approves that check for the repository. A new check is a gate
  decision; see the always-on safety rules.
- The frontend type check in the gate covers the generated files. Do not
  snapshot generated text in a test.
- A JavaScript frontend references the generated types from JSDoc
  comments.

## Existing hand-written types

- Hand-written types for backend data that exist before this rule are
  legacy to migrate, not precedent for new code.
- Generate every new boundary type from the start.
- When you change a hand-written type, move that type to the generated
  set in the same change, and point its importers at the generated file.
- Track the rest of the migration in a plan; see the `plans` skill.

From futex-ai/skills, MIT.

More from futex-ai/skills