typescript-best-practices

Applies TypeScript type-safety rules and patterns when reading or editing .ts and .tsx files.

Updated Sep 23, 2026
One-click install
npx skills add https://github.com/lucasheriques/pstack --skill typescript-best-practices-lucasheriques
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: typescript-best-practices
Source: https://github.com/lucasheriques/pstack/tree/main/skills/typescript-best-practices
Command: npx skills add https://github.com/lucasheriques/pstack --skill typescript-best-practices-lucasheriques

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? TypeScript codebases accumulate unsafe patterns like any types, unchecked as casts, and optional-field bags that let invalid states compile and crash at runtime. This Skill enforces a consistent set of type-system rules so code models only valid states and validates external data at boundaries. ## Core Features & Use Cases - Type modeling rules: Enforces discriminated unions, branded types, constructive modeling, and exhaustiveness checks so impossible states cannot be represented. - Boundary validation guidance: Directs parsing of external data as unknown with schema libraries like zod, deriving types via z.infer instead of hand-written guards. - Narrowing hierarchy: Ranks narrowing techniques from discriminant switches down to as casts as a last resort, with code examples in references/patterns.md. - Use Case: While editing a React component that handles an API response, the Skill guides you to parse the payload with a zod schema, model loading/ready/error states as a discriminated union, and add an exhaustiveness check in the render switch. ## Quick Start Ask the assistant to review or edit a TypeScript file and apply the typescript-best-practices rules to replace unsafe casts and any types with validated, strongly typed models.

Frequently Asked Questions about typescript-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I replace any types with unknown in TypeScript?▼

Declare external data as unknown and narrow it before use with typeof, instanceof, or the in operator. Sources like JSON.parse, RPC payloads, and environment variables should always start as unknown, then be validated at the boundary into a named domain type.

How to model loading and error states in TypeScript?▼

Use a discriminated union with a literal kind field, such as variants for loading, ready, and error, instead of a boolean plus optional fields. This makes contradictory states unrepresentable and lets the compiler narrow automatically in switch statements.

Should I use zod schemas or hand-written type guards?▼

Prefer the repository's existing runtime schema library and derive the TypeScript type from the schema, such as z.infer. Hand-written property-by-property guards drift from the schema over time, so only write them when no schema library exists in the codebase.

When is an as cast acceptable in TypeScript?▼

An as cast is acceptable only after full runtime validation has verified the claim, such as at the end of a parse function that checks every field. Every unvalidated cast is a potential runtime crash, so prefer satisfies, narrowing, or branded types first.

What are branded types in TypeScript used for?▼

Branded types attach a readonly __brand property to primitives so values like AgentId and UserId cannot be mixed up at compile time. Validate the raw value once at the boundary, then downstream code trusts the branded type without re-checking.

When should I not strengthen a TypeScript type?▼

Keep a plain T[] when every operation on it stays total, such as summing an empty array. Strengthen to NonEmpty<T> only where the loose type forces a non-null assertion, a cast, or a should-never-happen throw at a use site.