TypeScript Tooling

Priority: P1 (OPERATIONAL)

Essential tooling for TypeScript development and maintenance.

Implementation Guidelines

• Compiler: Use

  tsc

  for CI builds;

  esbuild

  or

  ts-node

  for development.
• Linting: Enforce

  ESLint

  with

  @typescript-eslint/recommended

  . Enable

  strict type checking

  .
• Formatting: Mandate

  Prettier

  via

  lint-staged

  and

  .prettierrc

  .
• Testing: Use

  Vitest

  (or

  Jest

  ) for unit/integration testing. Target

  > 80%

  line coverage.
• Builds: Use

  tsup

  (for library bundling) or

  Vite

  (for web applications).
• TypeScript Config: Ensure

  tsconfig.json

  has

  strict: true

  ,

  noImplicitAny: true

  , and

  esModuleInterop: true

  .
• CI/CD: Always run

  tsc --noEmit

  explicitly in the build pipeline to catch type errors.
• Error Supression: Favor

  @ts-expect-error

  over

  @ts-ignore

  for documented edge-cases.

ESLint Configuration

Strict Mode Requirement

CRITICAL: Every file in the project, including tests (

.spec.ts

), must adhere to strict type-checked rules. NEVER turn off

@typescript-eslint/no-explicit-any

or

no-unsafe-*

rules.

Common Linting Issues & Solutions

Request Object Typing

Problem: Using

any

for Express request objects or creating duplicate inline interfaces. Solution: Use the centralized interfaces in

src/common/interfaces/request.interface.ts

.

import { RequestWithUser } from 'src/common/interfaces/request.interface';

Unused Parameters

Problem: Function parameters marked as unused by linter. Solution: Prefix the parameter with an underscore (e.g.,

_data

) or remove it. NEVER use

eslint-disable

.

Test Mock Typing

Problem: Jest mocks triggering unsafe type warnings when

expect.any()

or custom mocks are used. Solution: Cast the mock or expectation using

as unknown as TargetType

.

mockRepo.save.mockResolvedValue(result as unknown as User);

Configuration

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitReturns": true,
    "noUnusedLocals": true
  }
}

Verification Workflow (Mandatory)

After editing any

.ts

/

.tsx

file:

1. Call

   getDiagnostics

   (typescript-lsp MCP tool) — surfaces type errors in real time.
2. Run

   tsc --noEmit

   in CI — catches project-wide errors LSP may miss.
3. Run

   eslint --fix

   — auto-fix formatting and lint violations.

getDiagnostics

is the fastest feedback loop. Use it before every commit on modified files.

LSP Exploration: Use

getHover

to inspect inferred types inline. Use

getReferences

before renaming any symbol to verify all call sites.

References

See references/REFERENCE.md for CI config, test setup, and advanced ESLint rules.