Typescript Engineering

TypeScript Engineering

Produce TypeScript that is explicit at boundaries, narrow in surface area, and strict enough that refactors fail fast. Prefer inference inside small scopes, explicit types at module boundaries, runtime validation for external data, and simple control flow over clever type tricks.

Workflow

1. Identify the boundary.

Library: optimize for stable public types, portability, and narrow exports. Application: optimize for operability, runtime validation, and maintainable module boundaries.

1. Model data before behavior.

Prefer discriminated unions, branded/domain types, and small interfaces over optional-field soup.

1. Decide where trust begins.

Treat network, env, file, CLI, and user input as unknown until validated.

1. Keep types and implementation aligned.

Prefer deriving types from values and functions over duplicating parallel definitions.

1. Use async intentionally.

Model failure and cancellation explicitly; avoid floating promises and hidden concurrency.

1. Verify before finalizing.

Run the project’s formatter, linter, type checker, and tests. Treat type errors as design feedback.

Load References By Need

| Need | Reference | |---|---| | Project shape, tsconfig, modules, exports, tooling | references/workflow.md | | Boundary validation, error handling, async and promises | references/runtime-and-errors.md | | API design, unions, narrowing, generics, utility types | references/types-and-api-design.md | | React/TSX state, props, hooks, and event typing | references/react-and-tsx.md | | Testing, mocks, fixtures, snapshots, review checklist | references/testing-and-quality.md | | Performance, allocation, iteration, and common footguns | references/performance-and-footguns.md |

Default Standards

• Enable strict mode and keep it on.
• Prefer unknown over any at trust boundaries.
• Validate external data at runtime before treating it as domain data.
• Prefer discriminated unions over boolean mode flags and optional-field matrices.
• Keep exports intentional. Avoid giant barrel files that hide ownership and increase coupling.
• Return typed domain values from core logic; isolate framework types at the edges.
• Use Promise and await intentionally. Do not leave floating promises.
• Prefer stable, readable types over maximally clever conditional-type machinery.

Code Review Checklist

• Are untrusted inputs validated before use?
• Are unions discriminated cleanly and narrowed safely?
• Are generic constraints actually helping, or just obscuring the code?
• Are async failures, cancellation, and promise lifetimes explicit?
• Are public exports and types narrower than the implementation internals?
• Is React state or prop modeling preserving invariants instead of pushing checks into render logic?
• Is the code relying on any, assertions, or non-null operators where better modeling would remove them?

Sources and Influences

This skill synthesizes ideas from the following public TypeScript skill work rather than copying any one source directly:

• alinaqi typescript: https://agent-skills.md/skills/alinaqi/claude-bootstrap/typescript
• Metabase typescript-write: https://agent-skills.md/skills/metabase/metabase/typescript-write
• cosmix typescript: https://agent-skills.md/skills/cosmix/claude-loom/typescript
• ilude typescript-workflow: https://agent-skills.md/skills/ilude/claude-code-config/typescript-workflow
• alexei-led writing-typescript: https://agent-skills.md/skills/alexei-led/claude-code-config/writing-typescript

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mfmezger
• Source: mfmezger/aiagent_dotfiles
• License: MIT

Install and usage instructions live in the source repository linked above.