できない.dev

TypeScript「type declarations for side-effect import」の原因と直し方

Cannot find module or type declarations for side-effect import は、*.css を宣言した .d.ts を置けば直る。
TypeScript 6.0 は CSS の import も行き先を検査するようになった。

公開:

症状できない · exit 2
npx tsc -p .
src/main.ts(1,8): error TS2882: Cannot find module or type declarations for side-effect import of './style.css'.
解決後できた · exit 0
npx tsc -p .

2026-11-07 に node:24(TypeScript 6.0.3 / Node.js 24.22.2) で実際に打って取った出力。検証環境の詳細

要約

error TS2882: Cannot find module or type declarations for side-effect import of './style.css'. は、値を受け取らない import(副作用 import)の行き先を TypeScript が見つけられないときに出るエラーだ。
import "./style.css" のように CSS を読み込むプロジェクトで出やすい。
declare module "*.css"; を書いた .d.ts を置けば通る。

5.x は、副作用 import の行き先が解決できなくても黙って通していた。
TypeScript 6.0 では noUncheckedSideEffectImports が既定で有効になり、型の宣言が無い行き先を検査で止める。

実行例

node:24 のコンテナで、CSS を import するだけのファイルを TypeScript 6.0.3 の tsc にかけた。
*.css を宣言すると通り、npm ls vite から後の Vite のプロジェクトでは types に "vite/client" を足すと終了コードが 0 になった。

$ npx tsc -v
Version 6.0.3
$ cat src/main.ts
import "./style.css";
 
console.log("loaded");
$ cat tsconfig.json
{
  "compilerOptions": {
    "noEmit": true,
    "module": "esnext",
    "moduleResolution": "bundler"
  },
  "include": ["src"]
}
$ npx tsc -p .
src/main.ts(1,8): error TS2882: Cannot find module or type declarations for side-effect import of './style.css'.
$ echo $?
2
$ cat src/env.d.ts
declare module "*.css";
$ npx tsc -p .
$ echo $?
0
$ cat src/typo.ts
import "./styel.css";
$ npx tsc -p .
$ echo $?
0
$ npm ls vite
vite-app@1.0.0 /opt/vite-app
`-- vite@8.3.6
$ npx tsc -p .
src/main.ts(1,8): error TS2882: Cannot find module or type declarations for side-effect import of './style.css'.
$ echo $?
2
$ cat tsconfig.json
{
  "compilerOptions": {
    "noEmit": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "types": ["vite/client"]
  },
  "include": ["src"]
}
$ npx tsc -p .
$ echo $?
0

— 2026-11-07 時点の出力

検証環境Node.js 24.22.2 / npm 11.19.1 / Python 3.11.2 / 2026-11-07 検証(ほか 2 件)
検証日
実行環境
node:24 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 24.22.2
  • npm 11.19.1
  • Python 3.11.2
  • Git 2.39.5
  • TypeScript 6.0.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. *.css の宣言を置く

// src/env.d.ts
declare module "*.css";

src の下の .d.ts は include で読まれる。
.scss や .svg なども読み込むなら、拡張子ごとに 1 行ずつ足す。

この宣言はワイルドカードなので、import "./styel.css" のように綴りを誤ったファイル名も通してしまう。
CSS のファイルの有無は、バンドラーがビルドのときに確かめる。

2. Vite は types に vite/client を足す

{
  "compilerOptions": {
    "types": ["vite/client"]
  }
}

vite/client は *.css のほか、画像や import.meta.env の型も持っている(Vite の Client Types(新しいタブで開く))。
src/vite-env.d.ts に /// <reference types="vite/client" /> を書く形でもよい。
Next.js 16 は next-env.d.ts が読む型の中で *.css を宣言しているので、next-env.d.ts を消していなければこのエラーは出ない。

3. 検査を止めるなら false にする

{
  "compilerOptions": {
    "noUncheckedSideEffectImports": false
  }
}

5.x と同じ挙動に戻る。
CSS の宣言を置く手間は無くなるが、行き先のファイルが無い import "./polyfill" も見逃すようになる。
止めたい行き先が CSS だけなら、1 の宣言を置く。

よくある原因

  1. TypeScript を 6.0 に上げた。
    CSS はバンドラーが読み込むもので、TypeScript から見ると型の宣言が無いファイルである。
    5.x では何も言われなかった import "./style.css" が、6.0 で TS2882 になる。
  2. Vite のプロジェクトで vite/client の型を読んでいない。
    vite/client は *.css の宣言を持っているが、src/vite-env.d.ts の /// <reference types="vite/client" /> も tsconfig.json の types の指定も無いと読まれない。
  3. 行き先のファイルが本当に無い。
    import "./polyfill" の polyfill.ts を消した、名前を誤った、という誤りも同じ TS2882 で止まる。
    この検査がもともと見つけたいのはこちらである。