Menu

Individual skill

typescript-best-practices

Sixteen type-safety rules for writing and reviewing TypeScript, with do and don't examples in references/patterns.md. Use whenever you open or edit a .ts or .tsx file, or on /typescript-best-practices.

plugins/requie/endostack/skills/typescript-best-practices/SKILL.md

Read pinned source

Source commit d780783eba4ecc7c8b9429f95c9362df95f07c61

What was checked

Matches the observed repository HEAD
Yes
Scanner rules are current
Yes
Repository scan complete
No
Skill scan complete
No
Observed behavior
Network or broad shell
Last checked
Nov 4, 2026

These are observations at the recorded commit, not a guarantee of safety. Review the source before running it.

Install this skill

Choose an agent in your Stack or copy a command below. Commands fetch the pinned commit and copy only this skill directory. Existing destinations are refused. Copying a command does not install anything.

An install command is unavailable: current rules, complete repository and skill scans, an eligible behavior level and a permitted license are required.

Repository context

Repository stars (not skill ratings)
1,532
Repository last updated
Nov 6, 2026
License
Apache-2.0

Observed agent integration: No specific integration evidence. Standard SKILL.md installation does not imply verified compatibility.

Files and excerpt

File metadata and permitted, redacted excerpts come from the recorded scan. Source links are pinned to that commit.

Browse files
Read excerpt

# typescript-best-practices

Read `principle-type-system-discipline` ([../principle-type-system-discipline/SKILL.md](../principle-type-system-discipline/SKILL.md)) first. These rules apply it to TypeScript. [references/patterns.md](references/patterns.md) has a short code example for each rule, numbered to match.

If your agent supports path-scoped skills, attach this one to `**/*.ts` and `**/*.tsx`. Otherwise the router or the user loads it when TypeScript is in play. For other languages, use `principle-type-system-discipline` and `principle-boundary-discipline` ([../principle-boundary-discipline/SKILL.md](../principle-boundary-discipline/SKILL.md)) directly.

Before you write anything, find the repo's existing conventions: its schema library, its logger, the name it uses for union tags, and the shape of its brand marker. Follow them over the examples in the reference.

## Modeling

1. **Tagged unions for variants.** Model alternative states as a union of object types that share one literal tag field. A boolean flag plus optional fields lets contradictory combinations exist (`loading: true` with an `error` set). Use one tag name across the codebase.
2. **Branded primitives.** Intersect a primitive with a readonly brand property so an `InvoiceId` cannot be passed where a `CustomerId` is expected. Mint the brand only through a type guard that validates (`value is InvoiceId`) and a parse function that wraps the guard and throws on failure. Never brand with `as`. Check once where the value enters; downstream code trusts the brand.
3. **Make illegal values unconstructible.** Prefer a shape that cannot hold a bad value to a runtime check: `[T, ...T[]]` for a non-empty list, `Array<[K, V]>` for paired data, a start plus a duration instead of start and end with an ordering invariant in a comment. Provide helpers for derived views (the computed end time). Brand the duration only if some unrelated number could be passed in its place.
4. **Use the simplest type that keeps every operation total.** A plain array is fine while every operation on it works for empty input (a sum of nothing is zero). Strengthen to non-empty only where the weak type forces a lie: a `!`, an index cast, or an "unreachable" throw. Or widen the return type to include `undefined`. Provide a guard so a plain array can be checked once and then carried as non-empty.