TypeScript

TypeScript conventions

every generated project gets this rule · no account needed
Currentas published in v1.5.1 — every generated project gets this rule

The rule

This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.

Types

  • strict is on and stays on. Do not weaken the compiler to pass.
  • Never any. Use unknown at boundaries and narrow with a type guard.
  • Prefer discriminated unions over optional properties for state — make the impossible states unrepresentable rather than merely unlikely.
  • Infer return types for local helpers; annotate them on exported functions, so a refactor cannot silently change a public signature.
  • readonly for anything not meant to be mutated, including arrays.

Validation at the edges

Anything arriving from outside the process — an API response, storage, a deep link, process.env — is unknown until validated. A cast is not validation:

ts
// No: the compiler believes you, the runtime does not.
const user = (await response.json()) as User;

// Yes: parsed, and wrong shapes fail here instead of three screens later.
const user = userSchema.parse(await response.json());

Nullability

  • Distinguish "absent" (undefined) from "explicitly empty" (null) and stay consistent about which one your code produces.
  • Use ?. and ?? for genuinely optional values, not to paper over a value that should always exist — if it should always exist, assert it at the boundary and keep the rest of the code honest.

Modules

  • Named exports. Default exports make renames invisible in review.
  • import type { … } for type-only imports.
  • No barrel file that re-exports an entire feature; it defeats tree-shaking and creates import cycles.

Async

  • async/await, not raw .then() chains.
  • Every await that can reject is either caught here or deliberately allowed to propagate — decide which, do not leave it to chance.
  • Promise.all for independent work; sequential await only when the second call genuinely needs the first result.

6 formats, one per tool

Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.

.cursor/rules/typescript.mdchand-written
---
description: TypeScript conventions
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

# TypeScript

## Types

- `strict` is on and stays on. Do not weaken the compiler to pass.
- Never `any`. Use `unknown` at boundaries and narrow with a type guard.
- Prefer discriminated unions over optional properties for state — make the
  impossible states unrepresentable rather than merely unlikely.
- Infer return types for local helpers; annotate them on exported functions, so
  a refactor cannot silently change a public signature.
- `readonly` for anything not meant to be mutated, including arrays.

## Validation at the edges

Anything arriving from outside the process — an API response, storage, a deep
link, `process.env` — is `unknown` until validated. A cast is not validation:

```ts
// No: the compiler believes you, the runtime does not.
const user = (await response.json()) as User;

// Yes: parsed, and wrong shapes fail here instead of three screens later.
const user = userSchema.parse(await response.json());
```

## Nullability

- Distinguish "absent" (`undefined`) from "explicitly empty" (`null`) and stay
  consistent about which one your code produces.
- Use `?.` and `??` for genuinely optional values, not to paper over a value
  that should always exist — if it should always exist, assert it at the
  boundary and keep the rest of the code honest.

## Modules

- Named exports. Default exports make renames invisible in review.
- `import type { … }` for type-only imports.
- No barrel file that re-exports an entire feature; it defeats tree-shaking and
  creates import cycles.

## Async

- `async`/`await`, not raw `.then()` chains.
- Every `await` that can reject is either caught here or deliberately allowed
  to propagate — decide which, do not leave it to chance.
- `Promise.all` for independent work; sequential `await` only when the second
  call genuinely needs the first result.

Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.

Advisory history

Every time this rule turned out to be wrong, and what we did about it.

No corrections yet

This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.

Pro tells you the day a correction lands that affects a repo you actually have.

See what Pro adds →
Put this rule in a real project

Every generated project gets this rule automatically — there is nothing to add. The wizard picks the rest of the stack with you and leaves a manifest, so check can tell you when any of it drifts.