TypeScript Strict Mode Rollout: A Compiler-Flag Checklist for Existing Projects
strict-modecompiler-optionsmigrationtype-safetytsconfig

TypeScript Strict Mode Rollout: A Compiler-Flag Checklist for Existing Projects

TTypeScript Website Editorial Team
2026-11-16
7 min read

A staged checklist for enabling TypeScript strict mode, prioritizing compiler flags, triaging errors, and tracking an existing project’s migration.

Enabling TypeScript strict mode in an existing project is less disruptive when treated as a staged migration rather than a single configuration change. This checklist explains how to order compiler flags, isolate errors, protect the build, and track progress across packages or directories without asking the team to fix every diagnostic at once.

Overview

TypeScript strict mode is a group of compiler checks designed to make assumptions in JavaScript code explicit. In a new project, enabling strict: true early is usually straightforward. In a mature codebase, the same change can reveal implicit any types, nullable values, unsafe callbacks, incomplete class initialization, and unchecked object access across application and test code.

The safest rollout has four properties:

  • It is staged. Enable related checks in an order that reduces dependency between errors.
  • It is scoped. Migrate a package, directory, or project reference instead of changing the entire repository at once.
  • It is measurable. Record the baseline and prevent new errors while existing errors are being removed.
  • It is reviewed. Prefer truthful types and runtime checks over broad casts that merely silence diagnostics.

Before changing flags, identify every TypeScript invocation used by the repository. Check package scripts, project references, editor settings, test runners, bundlers, and CI. A configuration that passes in an editor but is not used by the production build does not represent completed migration work.

Checklist by scenario

1. Establish a clean baseline

  • Confirm the TypeScript version used in local development and CI.
  • Run the same type-check command used for the release build.
  • Save the initial diagnostic count, grouped by code and directory.
  • Decide whether generated files, vendor code, tests, and migration shims belong in the first scope.
  • Choose a boundary: a package in a monorepo, a feature directory, or a small set of files.

A shared base configuration can keep the rollout consistent while allowing a migrated project to opt into stricter checks:

// tsconfig.base.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": false,
    "noEmit": true
  }
}

// packages/orders/tsconfig.json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true
  },
  "include": ["src", "tests"]
}

Use options that match your module system and build tooling; the important pattern is inheritance plus a deliberate scope, not these exact module settings.

2. Enable the core strict checks

Start with strict: true for a new scope when practical. This enables the main strict family together, including checks associated with implicit any, nullability, function variance, method binding, class property initialization, and implicit this. The exact set should be confirmed against the TypeScript version used by the project.

If the initial error set is too large, split the work while preserving the end goal:

  1. noImplicitAny: Add parameter, variable, and return types where inference cannot determine a safe type. Avoid replacing every error with any; use a domain type, a generic, or unknown where appropriate.
  2. useUnknownInCatchVariables: Treat caught values as untrusted. Narrow them with instanceof Error, a custom type guard, or a structured error check before reading properties.
  3. strictNullChecks: Decide which values can be absent and model that in the type. Fix the source of the uncertainty rather than adding non-null assertions throughout the call chain.
  4. strictPropertyInitialization: Initialize class fields in declarations or constructors, or make their lifecycle explicit with a carefully justified design.

3. Add boundary-focused checks

After the core strict family is stable, add checks that expose unsafe assumptions at common application boundaries:

  • noUncheckedIndexedAccess: Indexed access and lookups can produce undefined. Handle missing array elements, map entries, and dictionary keys before use.
  • exactOptionalPropertyTypes: Distinguish an omitted optional property from a property explicitly set to undefined. Review object builders, patch payloads, and configuration merges.
  • noImplicitOverride: Mark intentional method overrides so refactors do not silently change inheritance behavior.
  • noPropertyAccessFromIndexSignature: Use indexed access for values represented by an index signature when that better communicates their dynamic nature.

These options often produce more design-level work than annotation work. They are valuable precisely because they make data contracts and missing-value behavior visible.

4. Track each migration unit

Use a simple progress record for each package or directory:

| Scope       | Flags enabled                         | Baseline | Remaining | Owner | Next step |
|-------------|----------------------------------------|----------|-----------|-------|-----------|
| orders/src  | strict, noUncheckedIndexedAccess      | 84       | 18        | A     | fix lookups |
| users/src   | strictNullChecks                       | 31       | 0         | B     | enable exact optional |
| shared/api  | noImplicitAny, useUnknownInCatchVariables | 12    | 4         | C     | type errors |

Once a scope is clean, keep its configuration strict and prevent regressions with CI. A separate project configuration or project reference is often easier to maintain than a growing list of file exclusions.

What to double-check

Diagnostic patternLikely causePreferred response
Parameter implicitly has an any typeUntyped callback or public functionType the input at the boundary; infer internal values where possible.
Object is possibly null or undefinedNullable API, missing lookup, or incomplete initializationGuard, provide a valid fallback, or change the domain type.
Object is possibly undefined after indexingnoUncheckedIndexedAccessCheck the key or use a lookup function that returns a defined result.
Property is incompatible with optional propertyexactOptionalPropertyTypesOmit the property, or explicitly include undefined in its type if that is meaningful.
Property has no initializerClass field is assigned outside the constructorInitialize it, make construction enforce it, or document a narrow assertion at the real lifecycle boundary.

Double-check runtime boundaries before trusting a type. TypeScript checks how code is written, not whether JSON, environment variables, database rows, or HTTP responses actually match an interface. For external data, pair strict types with runtime validation or explicit parsing. This is especially important when migrating API clients and configuration code.

Also inspect declaration files and package boundaries. A strict application can still receive weak types from a JavaScript dependency, an inaccurate declaration, or an internal package that emits broad types. When the issue is a library boundary, consider improving its declarations rather than scattering casts across consumers. See the guide to writing TypeScript declaration files for JavaScript libraries for that workflow.

Common mistakes

  • Turning on every option at once: A large diagnostic burst makes ownership and prioritization difficult. Stage flags by scope and record each change.
  • Using as any as a migration strategy: A temporary suppression can be justified at a difficult boundary, but it should have an owner, a comment, and a removal task.
  • Overusing non-null assertions: value! hides uncertainty without proving that the value exists. Prefer a guard or a function whose return type reflects successful validation.
  • Fixing symptoms in consumers: If many files need the same cast, repair the shared type, parser, declaration, or factory instead.
  • Ignoring tests and scripts: Test fixtures, mock factories, migration scripts, and build utilities often expose different assumptions from production code. Include them deliberately or document why they are separate.
  • Confusing compilation with runtime safety: Strict mode cannot validate untrusted input. Keep parsing and runtime validation at system boundaries.

When to revisit

Revisit this checklist before a seasonal planning cycle, after a TypeScript upgrade, when a new package joins the repository, or whenever build and editor diagnostics begin to differ. Compiler options, defaults, diagnostics, and library declarations can change with toolchain updates, so verify the migration against the version actually installed rather than relying on an old configuration example.

At each review, take these actions:

  1. Run the release-equivalent type-check command and refresh the diagnostic baseline.
  2. Compare enabled flags with the current project standard and identify one next scope.
  3. Search for new broad casts, non-null assertions, and suppression comments introduced since the last review.
  4. Confirm that package boundaries, generated declarations, tests, and runtime validation still match the intended contracts.
  5. Remove obsolete exclusions and migration shims when the affected scope is clean.

Strict mode is complete when it is part of the project’s normal development path, not merely when a configuration file contains strict: true. A staged checklist turns that setting into a maintainable practice: each scope has a clear owner, each diagnostic has a reasoned fix, and every future package starts from a stronger type-safety baseline.

For related implementation work, compare this process with the file-by-file JavaScript to TypeScript migration guide, the TypeScript project configuration and CI checklist, and the TypeScript error troubleshooting reference.

Related Topics

#strict-mode#compiler-options#migration#type-safety#tsconfig
T

TypeScript Website Editorial Team

Senior SEO Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.