Cursor Rule: Strict TypeScript

Auto-attached .cursor/rules/typescript.mdc that enforces strict TypeScript conventions on every .ts/.tsx file in context.

License: CC0-1.0 · By waxmark · v1 · 2026-11-02

Share on X

Add a trust badge to your README

[![Waxmark](https://waxmark.app/api/badge/cursor-rule-typescript-strict)](https://waxmark.app/items/cursor-rule-typescript-strict/scan)
Report
---
description: Strict TypeScript conventions for all .ts and .tsx source files
globs: **/*.ts, **/*.tsx
alwaysApply: false
---

# TypeScript conventions

`tsconfig.json` has `strict: true`, `noUncheckedIndexedAccess: true`, `exactOptionalPropertyTypes: true`, and `verbatimModuleSyntax: true`. Code must compile under those flags; do not weaken them.

## Types

- No `any`. Use `unknown` at boundaries and narrow with a type guard or a `zod` schema before use.
- No non-null assertions (`x!`). Narrow with `if (!x) throw/return` or use optional chaining with a default.
- No `as` casts except `as const` and `satisfies`. If a cast seems necessary, write a type guard function (`function isFoo(v: unknown): v is Foo`).
- Prefer `interface` for object shapes that may be extended, `type` for unions, tuples, and mapped types. Do not mix for the same concept within a module.
- Discriminated unions over optional fields: `{ kind: 'ok'; value: T } | { kind: 'err'; error: E }`, not `{ value?: T; error?: E }`.
- Index access returns `T | undefined` under `noUncheckedIndexedAccess`; handle it, do not assert it away.
- Exported functions declare explicit return types. Internal helpers may infer.
- Use `readonly` on arrays and object properties that are not mutated. Use `ReadonlyArray<T>`/`readonly T[]` in parameters.

## Modules

- `import type { X }` for type-only imports; `verbatimModuleSyntax` requires it.
- Named exports only. No `export default` except where a framework requires it (Next.js pages/layouts, config files).
- One module per concept. Barrel `index.ts` files only at package boundaries, never inside `src/` subfolders.
- No circular imports. If two modules need each other, extract the shared type into a third.

## Null, errors, async

- Use `undefined`, not `null`, for absent values in our own types. Convert `null` from external APIs at the boundary.
- Throw `Error` subclasses with a `name` and a stable `code` field; never throw strings or plain objects.
- Every `async` function is awaited or its promise is explicitly returned or handled with `.catch`. No floating promises (`@typescript-eslint/no-floating-promises` is on).
- Prefer `Result`-style returns (`{ ok: true, value } | { ok: false, error }`) for expected failures; reserve `throw` for bugs and unrecoverable states.

## Style

- `const` by default; `let` only when reassigned; never `var`.
- Enums: use `as const` objects with a derived union type, not `enum`.
- Prefer `for...of` and array methods over index loops; prefer `Map`/`Set` over objects used as dictionaries.
- Function parameters: more than three becomes a single options object with an explicit interface.
- Fix lint and type errors at the source. `// eslint-disable-next-line` and `// @ts-expect-error` need a trailing reason, and `// @ts-ignore` is never allowed.

## Before finishing

Run `tsc --noEmit` (or the project's typecheck script) and the linter on the files you changed and fix everything they report.
Cursor Rule: Strict TypeScript · Waxmark