TypeScript Reference ยท tsconfig: Type Checking Options
TypeScript noUncheckedSideEffectImports option
Reference for noUncheckedSideEffectImports: make bare import statements such as import './setup.js' fail when the file cannot be resolved.
A side-effect import has no bindings: import "./polyfills.js";. It is written only to run the module's top-level code. Historically TypeScript resolved such imports on a best-effort basis and stayed silent when it could not find the file, because plain stylesheets (import "./theme.css") and similar assets have no TypeScript declaration.
noUncheckedSideEffectImports makes the compiler treat these imports like any other: if the specifier cannot be resolved to a file with a declaration, it reports an error (TS2882, "Cannot find module or type declarations for side-effect import"). That catches typos in setup files that would otherwise fail only at runtime.
import "./polyfills.js"; // checked when the option is on import "./theme.css"; // needs a declaration such as: declare module "*.css";
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
{ "compilerOptions": { "noUncheckedSideEffectImports": true } }
| Part | Description |
|---|---|
| Type | boolean. Check the default for your version; set it explicitly to make the behavior obvious. |
| Command line | tsc --noUncheckedSideEffectImports |
| Added in | TypeScript 5.6. |
| Error | TS2882 when a bare import "x" has no matching file or ambient module. |
Usage notes
- Only bare imports are affected.
import x from "y"andimport { a } from "y"were always checked. - Non-code assets need an ambient declaration so the import counts as found. A file containing
declare module "*.css";(or*.scss,*.svg) in your project is enough. - Resolution follows your
moduleandmoduleResolutionsettings, so a relative import in Node ESM mode needs the real extension (./setup.js). - Side-effect imports are never removed during emit, even with
verbatimModuleSyntaxoff. They are the one import form that always survives. - Dynamic
import()calls are expressions and are not covered by this option. - Typical mistakes it reveals: a renamed polyfill file, a missing
.jsextension, a stylesheet import without a*.cssdeclaration.