Skip to content

Stricter TypeScript Configuration

Status

Proposed

Date

2025-03-06

Context

As our codebase grows, we've experienced increased development time fixing simple TypeScript errors, particularly around unused variables and parameters. These issues are often only caught during code review rather than during development. Additionally, we've found that our package dependency management is inconsistent, with build-time dependencies sometimes placed in regular dependencies rather than devDependencies.

We need a consistent approach to TypeScript's type checking strictness and package dependency management to improve code quality and reduce maintenance overhead.

Decision

We have decided to:

  1. Enable stricter TypeScript compiler options across the monorepo:

  2. Enable noUnusedLocals: true in the base tsconfig

  3. Enable noUnusedParameters: true in the base tsconfig

  4. Already have exactOptionalPropertyTypes: true enabled

  5. Create automated tooling to help developers transition to and maintain these stricter settings:

  6. Create a strict-ts-fix.ts script to automatically fix common issues

  7. Create a dependency-check.ts script to identify dependencies that should be in devDependencies

  8. Document architectural decisions with Architecture Decision Records (ADRs):

  9. Create an ADR template and directory structure
  10. Implement a create-adr.ts script to streamline the process
  11. Begin documenting significant architectural decisions

Consequences

Positive

  • Improved code quality with fewer unused variables and parameters
  • Earlier detection of potential issues during development
  • Reduced bundle sizes with proper dependency categorization
  • Better documentation of significant architectural decisions
  • Automated tools to help developers follow best practices
  • Consistent approach to code quality across the codebase

Negative

  • Short-term increase in TypeScript errors as we enforce stricter rules
  • Migration effort required to fix existing code
  • Potential need to update CI pipelines to run new checks
  • Learning curve for team members to adjust to new processes

Neutral

  • Some existing code may need to be refactored to comply with stricter settings
  • Regular maintenance required to keep automated tools up to date

Alternatives Considered

  1. Gradual enabling of strict settings in specific packages:

  2. Rejected because it would lead to inconsistency across the codebase and make it harder to enforce standards

  3. Using ESLint rules instead of TypeScript compiler options:

  4. Rejected because compiler options provide better integration with IDEs and build tools

  5. Manual enforcement through code reviews:

  6. Rejected as too time-consuming and error-prone

  7. Using third-party dependency analysis tools:

  8. Rejected in favor of a custom solution that can be tailored to our specific needs

References