TypeScript Strict Mode Plugin

2.4.4 · active · verified Sun Apr 19

The `typescript-strict-plugin` enables gradual adoption of TypeScript's strict mode in existing large projects. Instead of refactoring an entire codebase at once, developers can configure this plugin to apply strict type checking to specific files or directories, or enable strict mode by default and opt out problematic files. The current stable version is 2.4.4. It offers a clear migration path with its `update-strict-comments` script, which automatically adds `//@ts-strict-ignore` comments to files containing strict errors. This allows new or refactored code to benefit from strict checks immediately, while legacy code can be addressed incrementally. It also provides a CLI tool, `tsc-strict`, to ensure compile-time strictness checks, as TypeScript language service plugins typically only affect IDE feedback. The project appears to have an active release cadence, with recent updates addressing bug fixes and compatibility. Its key differentiator is providing a flexible, file-level control over strict mode, effectively solving the "all-or-nothing" barrier for large-scale migrations.

Common errors

```
Error: Plugin 'typescript-strict-plugin' not found. Make sure it's installed and listed in your tsconfig.json.
```
cause The plugin is not installed as a `devDependency` or its name is misspelled in `tsconfig.json`.

fix Run `npm install --save-dev typescript-strict-plugin` and verify that `"name": "typescript-strict-plugin"` is correctly configured in your `tsconfig.json` under `compilerOptions.plugins`.
```
tsc-strict: command not found
```
cause The `tsc-strict` executable is not in your system's PATH when you try to run it directly.

fix Execute `tsc-strict` using `npx tsc-strict` or by defining a script in your `package.json` (e.g., `"scripts": { "strict-check": "tsc-strict" }`) and running `npm run strict-check`.
```
Strict errors are not appearing in my terminal when I run `tsc`.
```
cause The plugin's primary function is for IDE feedback. The default `tsc` command does not run the plugin's strictness checks.

fix You need to integrate the `tsc-strict` CLI tool into your build process. Add it to a `package.json` script, for example: `"scripts": { "build": "tsc --noEmit && tsc-strict" }`.
```
My files are still showing strict errors even with `//@ts-strict-ignore` at the top.
```
cause The `//@ts-strict-ignore` comment might not be at the absolute top of the file, or your `tsconfig.json` has `"strict": true`, overriding the plugin.

fix Ensure `//@ts-strict-ignore` is the very first line of your file. Also, confirm that `"strict": false` is set in your `compilerOptions` within `tsconfig.json` for the plugin to take effect.

Warnings

breaking Version 2.0 introduced a breaking change by inverting the default strictness behavior. Previously, files were non-strict by default and opted-in with `//@ts-strict`. Now, files are strict by default and opt-out using `//@ts-strict-ignore`.
Fix: Run `npx update-strict-comments` to automatically add `//@ts-strict-ignore` to files with strict errors, ensuring a smooth transition from v1 to v2.
gotcha TypeScript Language Service Plugins (like this one) primarily affect IDE feedback. To enforce strict checks at compile-time during your build process, you *must* use the `tsc-strict` CLI utility provided by the package.
Fix: Add `tsc-strict` to your `package.json` scripts (e.g., `"typecheck": "tsc --noEmit && tsc-strict"`) and run it as part of your build pipeline.
gotcha For the plugin to manage partial strictness (i.e., making some files strict while others are not), your `tsconfig.json`'s `compilerOptions.strict` flag must be set to `false`. If `strict` is `true`, the plugin's effect will be overridden by the global compiler setting.
Fix: Ensure `"strict": false` is explicitly set in your `tsconfig.json` under `compilerOptions`.
gotcha Command-line arguments passed to `tsc-strict` (e.g., `--strictNullChecks false`) will override the compiler options configured in your `tsconfig.json` for the strict checks performed by `tsc-strict`. This can lead to unexpected behavior if not understood.
Fix: Be mindful when passing arguments to `tsc-strict`. Only override specific options when you intend to temporarily deviate from your `tsconfig.json` settings.
gotcha The `//@ts-strict-ignore` comment must be placed at the very top of a TypeScript file to be effective in disabling strict checks for that file. If it's not the first line (after any shebang or license comments), it may not be parsed correctly by the plugin.
Fix: Ensure `//@ts-strict-ignore` is the first meaningful line of code or comment in the file you wish to ignore.

Install

npm install typescript-strict-plugin npm
yarn add typescript-strict-plugin yarn
pnpm add typescript-strict-plugin pnpm

Imports

typescript-strict-plugin (in tsconfig.json)
wrong:
```
{ "plugin": "typescript-strict-plugin" }
```
correct:
```
{ "name": "typescript-strict-plugin" }
```
This package is a TypeScript Language Service Plugin and is configured directly in your `tsconfig.json`'s `compilerOptions.plugins` array, not imported as a JavaScript module.
update-strict-comments
wrong:
```
node update-strict-comments
```
correct:
```
npx update-strict-comments
```
This is a CLI utility included with the package. It should be executed via `npx` or referenced from `./node_modules/.bin/` to ensure the correct executable is found. It helps migrate projects to v2 by adding `//@ts-strict-ignore` comments.
tsc-strict
wrong:
```
tsc-strict
```
correct:
```
npm run typecheck
```
This is a CLI utility for compile-time strictness checks. It's best used as part of a `package.json` script, e.g., `"typecheck": "tsc && tsc-strict"`, to ensure it runs in the correct environment and path. Direct execution might fail if not in the system's PATH.

Quickstart

This quickstart demonstrates how to install `typescript-strict-plugin`, configure it in `tsconfig.json` to enable partial strictness, run the `update-strict-comments` migration script, and integrate `tsc-strict` into your `package.json` scripts for compile-time checking.

{
  "name": "my-strict-project",
  "version": "1.0.0",
  "devDependencies": {
    "typescript": "^5.0.0",
    "typescript-strict-plugin": "^2.0.0"
  },
  "scripts": {
    "typecheck": "tsc --noEmit && tsc-strict"
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "strict": false, // Crucial: Set to false for the plugin to manage strictness
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "plugins": [
      {
        "name": "typescript-strict-plugin",
        "paths": ["./src"], // Optionally specify paths to make strict by default
        "excludePattern": ["**/*.spec.ts"]
      }
    ]
  },
  "include": ["src/**/*.ts"]
}

// 1. Install dependencies
// npm install --save-dev typescript typescript-strict-plugin

// 2. Run the migration script to ignore files with existing errors
// npx update-strict-comments

// 3. To run compile-time strict checks
// npm run typecheck

view raw JSON →