TypeScript

Specification

The words

MUST

MUST NOT

REQUIRED

SHALL

SHALL NOT

SHOULD

SHOULD NOT

RECOMMENDED

MAY

, and

OPTIONAL

are interpreted as described in RFC 2119.

<prerequisite> This skill extends the JavaScript preference skill. You MUST load `javascript` first for naming, module style, async patterns, and general JavaScript conventions. </prerequisite>

Types encode intent. Let the compiler prove the rest.

You MUST use TypeScript 7.0 as the baseline. You MUST carry TypeScript 6.0 migration guidance forward: 7.0 is expected to match 6.0 checking and command-line behavior, adopt the 6.0 defaults, and hard-error on constructs and flags deprecated in 6.0.

References

Topic	Reference	Load when
Configuration and TS 6-to-7 migration	`references/configuration.md`	Updating tsconfig, module resolution, compiler directives, native tooling
Generics and type-level programming	`references/generics.md`	Designing reusable generic APIs, utility types, mapped/conditional/template literal types
Narrowing and type guards	`references/narrowing.md`	Modeling variants, validating unknown values, writing exhaustive code
Patterns and declarations	`references/patterns.md`	Choosing interfaces/types/enums/classes/brands/overloads/callback signatures

Baseline

You MUST treat TypeScript 7.0 as stable project direction. The native Go compiler and language service are the expected direction for type checking, editor tooling, and performance-sensitive validation.
You MUST use 6.0 as the compatibility bridge: code that passes 6.0 with stable type ordering and without deprecated flags SHOULD be ready for 7.0.
You SHOULD prefer explicit, domain-shaped types over clever type-level machinery. Stay at the simplest type complexity tier that proves the behavior.
You MUST match the project's established conventions first. If a project contradicts this skill, follow the project locally and flag the divergence once.

Type Safety

Strict mode is REQUIRED. TS 7.0 defaults to strict checking; keep
```
strict: true
```
explicit in shared configs when clarity helps.
You MUST use
unknown
for untrusted values. Narrow API, JSON, user input, and caught values before use. Temporary
```
any
```
is acceptable only for migrations or mocks, with a short comment explaining why.
You SHOULD avoid non-null assertions. Narrow instead. If
```
!
```
is truly needed, explain the invariant near the assertion.
You SHOULD prefer annotations and
satisfies
over assertions. Use
```
satisfies
```
to validate literals without widening; use annotations where intentional widening or public API shape matters. Use
```
as
```
only when you know more than the compiler.
You MUST use
import type
and
export type
for type-only imports and re-exports.
You MUST NOT suppress type errors casually. Prefer fixing the type. Use
```
@ts-expect-error
```
only for deliberate invalid examples or tests, with a comment. Do not use
```
@ts-ignore
```
or
```
@ts-nocheck
```
in production code.

Modeling

You SHOULD use discriminated unions for variants. Use a
```
kind
```
,
```
type
```
, or similarly stable literal discriminator and exhaustive handling.
You SHOULD use interfaces for object shapes and type aliases for everything else. Use
```
type
```
for unions, intersections, tuples, function types, mapped types, and conditional types.
You SHOULD use literal unions or
as const
maps for simple constants. Use string enums only when a real runtime object or namespace is useful. Avoid implicit numeric enums and mixed enum members.
Branded types for nominal safety. Use them for domain IDs, validated strings, and units that MUST NOT be mixed.
Keep nullability at use sites. Prefer
```
function find(): User | null
```
over spreading
```
MaybeUser
```
aliases through the codebase.
Use
Record<K, V>
for dictionary-shaped data. Prefer specific key unions when possible.

Generics

You SHOULD let inference work. Do not specify type arguments when the compiler can infer them.
You SHOULD constrain generics with
```
extends
```
when the implementation requires structure.
You SHOULD avoid return-type-only generics; callers SHOULD NOT have to guess type arguments.
You SHOULD use built-in utility types (
```
Partial
```
,
```
Pick
```
,
```
Omit
```
,
```
Record
```
,
```
ReturnType
```
,
```
Parameters
```
,
```
Awaited
```
,
```
NoInfer
```
) instead of hand-rolled equivalents.
You SHOULD use
```
NoInfer<T>
```
when one parameter MUST be checked against another parameter's inferred type without driving the inference itself.
Reserve conditional, mapped, template literal, and recursive types for library/framework code or places where they remove more complexity than they add.

Configuration

TS 7.0 defaults MUST be treated as normative:
```
strict
```
is on,
```
module
```
defaults toward
```
esnext
```
, and
```
target
```
defaults toward the stable ECMAScript version immediately before
```
esnext
```
.
You SHOULD prefer modern configuration:
- Bundled apps:
```
module: "preserve"
```
  ,
```
moduleResolution: "bundler"
```
  ,
```
noEmit: true
```
  .
- Direct Node output:
```
module: "nodenext"
```
  , with package
```
type
```
  and emitted file extensions handled deliberately.
- Use
```
verbatimModuleSyntax
```
  ,
```
isolatedModules
```
  ,
```
moduleDetection: "force"
```
  , and explicit
```
types
```
  .
You MUST NOT depend on TS 6.0-deprecated paths in new work: legacy ES5 targeting, classic/node10-style resolution,
```
baseUrl
```
as a lookup root,
```
import ... asserts
```
,
```
outFile
```
, or AMD/UMD/SystemJS module targets.
You SHOULD use
```
stableTypeOrdering
```
while validating 6.0-to-7.0 migrations when type-display or declaration-order stability matters.

Application

When writing TypeScript:

You MUST apply these conventions without narrating each one.
You MUST keep exported functions, public methods, and package boundaries explicitly typed.
You SHOULD keep local implementation types inferred when inference is clear.
You MUST use runtime validation at trust boundaries; types do not validate data at runtime.

When reviewing TypeScript:

You MUST lead with concrete bugs, unsoundness, or migration risks.
You SHOULD show the smallest correction inline.
You MUST separate style preferences from type-safety issues.

typescript

NPX Install

Tags

SKILL.md Content