alexei-led/writing-typescript

TypeScript Development

Scope

• Use for .ts and .tsx, Node.js services, React apps, typed APIs, and TypeScript design advice.
• Do not use for Go, Python, plain HTML/CSS/JS, or server-rendered templates.
• Follow the repository's TypeScript version, tsconfig, package manager, framework, test runner, and lint rules.
• Do not add dependencies or switch frameworks unless the project already uses them or the user approves.

Reference Reads

• Read only the references needed for the task.
• Read references/principles.md for non-trivial TypeScript changes or reviews.
• Read references/patterns.md for data models, validation, async flow, or module boundaries.
• Read references/react.md for .tsx, hooks, component state, forms, performance, or React tests.
• Read references/testing.md before adding or changing TypeScript tests.

Defaults

• Preserve strict typing; do not weaken compiler options to pass checks.
• Use unknown for untrusted input. Avoid any; isolate it only for unavoidable interop.
• Validate API, JSON, env, storage, and form data at the boundary before typed use.
• Use discriminated unions for variants, async state, and domain states.
• Use guard clauses and focused helpers. Avoid deep nesting, global state, and mixed concerns.
• Use the project's error conventions; prefer unions or Result for recoverable failures.
• Pass dependencies explicitly; avoid inheritance, singletons, and hidden module state.
• Avoid unsafe casts, non-null assertions, broad index signatures, boolean-flag state, and new app enums where literal unions fit.

Testing and Verification

• For behavior changes, include success and failure tests. For React, cover affected user-visible states.
• Run the project's configured typecheck, tests, lint, and format checks for the changed package or workspace.
• Report checks run, failures, and unchecked risks. Do not claim success without a clean check or an explicit reason it was skipped.

Failure Handling

• If project root is unclear, identify the nearest package.json and tsconfig.json; in monorepos, state the selected package.
• If strict compiler options are absent, do not silently weaken new code. State the gap and keep the change locally type-safe.
• If validation needs a schema/form library not already used, ask before adding it; otherwise use a narrow type guard.
• If typecheck or tests fail, quote the exact diagnostic or failing assertion, state the cause, and fix the type/model boundary before widening types.
• Do not run destructive shell commands. For broad or risky changes, state the risk and ask before acting.