# Ts Best Practices

TypeScript type safety guidelines for writing maximally type-safe code.

- Repository: https://github.com/poteto/noodle (577 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-03-19
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add poteto/noodle --skill ts-best-practices -g -a claude-code -y`
Codex: `npx skills add poteto/noodle --skill ts-best-practices -g -a codex -y`
Cursor: `npx skills add poteto/noodle --skill ts-best-practices -g -a cursor -y`
Gemini CLI: `npx skills add poteto/noodle --skill ts-best-practices -g -a gemini-cli -y`

## Description

TypeScript type safety guidelines for writing maximally type-safe code. Apply these patterns when writing or reviewing any TypeScript: discriminated unions, type narrowing, type guards, exhaustiveness checks, avoiding `as` casts, preferring `unknown` over `any`, and making impossible states unrepresentable. Use this skill whenever writing TypeScript code, reviewing TypeScript for type safety issues, or when the user mentions type safety, type narrowing, discriminated unions, or asks to make types stricter/more explicit.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Type Safety

This project's TypeScript policy. Apply when writing or reviewing TypeScript.

| Rule | Summary |
|------|---------|
| No `as` casts | Every `as` is a potential runtime crash. Validate at boundaries, then cast only if earned. Prefer Zod/Valibot over manual validation. |
| `unknown` over `any` | `any` disables type checking for everything it touches. External data is always `unknown`. |
| Discriminated unions | Model variants with a shared literal discriminant. No optional-field bags. |
| Narrowing hierarchy | Prefer: discriminated union switch > `in` operator > typeof/instanceof > type guard > `as` |
| Type guards | Must actually verify the claim. Name them `isX` or `hasX`. Prefer discriminant narrowing when possible. |
| Exhaustiveness checks | Always add `default: never` arm to switches over discriminated unions. Use an `absurd()` helper to reduce boilerplate. |
| `satisfies` over `as` | When verifying a value matches a type without widening, use `satisfies` to preserve literal types. |
| Impossible states | If a bug requires asking "can this combination happen?" the type is too loose. Tighten it. |

Read [references/patterns.md](references/patterns.md) for code examples of each rule.