Skip to main content

Type-aware linting readiness

Use this guide before enabling type-aware presets or rules in a large codebase.

When this guide appliesโ€‹

Use this checklist when adopting:

  • recommended-type-checked
  • strict or all in projects with type-aware rules
  • ts-extras/type-guards

Readiness checklistโ€‹

1) Parser-service availabilityโ€‹

Confirm the lint runtime can provide full type services:

  • ESLint uses @typescript-eslint/parser
  • your lint config resolves the intended tsconfig(s)
  • the targeted files are included in those tsconfig(s)

2) Project graph stabilityโ€‹

Before enabling strict typed checks:

  • npm run typecheck is green
  • baseline linting is green (or has a controlled known backlog)
  • generated types/artifacts are not stale

3) Performance baselineโ€‹

Capture a baseline to detect regressions:

npx eslint "src/**/*.{ts,tsx}" --stats

Track:

  • total runtime
  • expensive files
  • hot rules that call type-checker operations frequently

4) CI gate orderingโ€‹

Prefer this order:

  1. typecheck
  2. lint (typed rules enabled)
  3. tests

This keeps typed-service failures easy to classify.

  1. Start with one package/folder.
  2. Enable type-aware rules as warn first.
  3. Fix baseline findings in small batches.
  4. Promote to error once the scope stays green.
  5. Expand scope incrementally.

Fast validation commandsโ€‹

npm run typecheck
npm run lint
npm run test

For focused typed checks during migration:

npx eslint "src/**/*.{ts,tsx}" --stats

Common failure modesโ€‹

"Typed rule requires type information"โ€‹

Likely causes:

  • file not included in the active tsconfig
  • parser-service wiring mismatch for the current workspace
  • incorrect project root assumptions in local/CI lint execution

Large runtime regressionsโ€‹

Likely causes:

  • expensive semantic checks on broad selectors
  • repeated checker calls without syntax prefilters
  • too-large rollout scope for first pass