Skip to content
Tutorials Center
My learning

Topics

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.

TypeScript
import "./polyfills.js";   // checked when the option is on
import "./theme.css";      // needs a declaration such as: declare module "*.css";

Try it

TypeScript A side-effect import that resolves

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.

TypeScript Side effects run once

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

JSON
{ "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" and import { 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 module and moduleResolution settings, so a relative import in Node ESM mode needs the real extension (./setup.js).
  • Side-effect imports are never removed during emit, even with verbatimModuleSyntax off. 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 .js extension, a stylesheet import without a *.css declaration.