TypeScriptでCSSのimportに出るTS2307の直し方

​​TypeScript​CSS Modules,Vite,トラブルシュート

tsc で error TS2307: Cannot find module './styles.module.css' or its corresponding type declarations. と出るのは、TypeScript が .module.css の型を知らないためです。CSS ファイル自体はあってもなくても、同じメッセージになります。declare module '*.module.css' を書いた宣言ファイルを置くか、Vite を使っているなら vite/client の型を読み込めば、エラーは消えます。

React や Vite のアプリで CSS Modules を使っていて、型チェック(tsc)でこのエラーが出たときや、エディターで CSS の import に赤い波線が出たときの、原因と直し方です。私は検証環境でこのエラーを起こし、出たメッセージをそのまま載せました。直すとエラーが消えることと、宣言ファイルを置いても消えない2つの書き方も確かめています。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4、TypeScript 7.0.2(tsc)、Vite 8.3.8 です。確かめたのは tsc での型チェックだけで、エディターでの表示や、Vite での実行・ビルドは試していません。

エラーを起こしたコードとメッセージ

src/main.ts で、同じフォルダーの styles.module.css を読み込みました。

ts
// src/main.ts
import styles from './styles.module.css'

const h1 = document.createElement('h1')
h1.className = styles.title
h1.textContent = 'CSS Modules'
document.body.append(h1)
css
/* src/styles.module.css */
.title {
  color: #067a98;
}

tsconfig.json は次のとおりです。Vite の react-ts テンプレートと同じ "moduleResolution": "bundler" にし、型チェックだけをするので noEmit を付けています。

json
{
  "compilerOptions": {
    "target": "es2022",
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "noEmit": true
  },
  "include": ["src"]
}

npx tsc の出力を端末以外(パイプなど)に流すと、次の1行が出て、終了コードは 1 でした。

console
$ npx tsc
src/main.ts(1,20): error TS2307: Cannot find module './styles.module.css' or its corresponding type declarations.

ターミナルで直接実行したときは、表示の形が変わり、該当箇所に波線が付きます(色は省いています)。

text
src/main.ts:1:20 - error TS2307: Cannot find module './styles.module.css' or its corresponding type declarations.

1 import styles from './styles.module.css'
                     ~~~~~~~~~~~~~~~~~~~~~


Found 1 error in src/main.ts:1

1:20(または (1,20))は、src/main.ts の1行目・20文字目、つまり './styles.module.css' の始まりです。

CSS ファイルがあるのに出る理由

ls src で確かめると、main.ts と styles.module.css は同じフォルダーに並んでいました。それでもエラーになります。

試しに styles.module.css の名前を変えて、ファイルがない状態にしてみました。出たメッセージは、一字一句同じでした。

console
$ mv src/styles.module.css src/styles.module.css.bak && ls src && npx tsc
main.ts
styles.module.css.bak
src/main.ts(1,20): error TS2307: Cannot find module './styles.module.css' or its corresponding type declarations.

TypeScript のモジュール解決の説明にあるとおり、TypeScript は import のパスを、型の情報を持てるファイル(.ts や .d.ts など)に結びつけようとします。検証では CSS ファイルがあってもなくても同じメッセージだったので、styles.module.css そのものは型の手がかりになっていません。このエラーは、メッセージの後半にある「対応する型の宣言(corresponding type declarations)」が見つからない、という意味です。

宣言ファイルで .module.css の型を教える

src に、次の css-modules.d.ts を置きました。

ts
// src/css-modules.d.ts
declare module '*.module.css' {
  const classes: { readonly [key: string]: string }
  export default classes
}

'*.module.css' のように * を1つ含む名前で書くと、その形に合う import のパスすべてに、この型が使われます。TypeScript のドキュメントでは、これを pattern ambient module(ワイルドカードを使ったモジュールの宣言) として説明しています。ここでは、default export がクラス名から文字列への対応表になる、という型にしました。

置いたあとで npx tsc を実行すると、何も出力されずに終わり、終了コードは 0 でした。

注意

この宣言を置くと、tsc は CSS ファイルがあるかどうかを確かめなくなります。検証では、存在しない ./missing.module.css を読み込むファイルを足しても、npx tsc は終了コード 0 で終わりました。ファイル名の書き間違いは、型チェックでは見つかりません。

Vite のプロジェクトなら vite/client を読み込む

Vite には、.module.css などの宣言が入った型(vite/client)が付いています。検証環境の Vite 8.3.8 の node_modules/vite/client.d.ts には、次の宣言がありました。

ts
type CSSModuleClasses = { readonly [key: string]: string }

declare module '*.module.css' {
  const classes: CSSModuleClasses
  export default classes
}

Vite の公式ドキュメントにある、クライアント側のコードの型(Client Types)の説明では、tsconfig.json の compilerOptions.types に vite/client を入れる方法と、/// <reference types="vite/client" /> と書いた宣言ファイル(vite-env.d.ts)を置く方法が紹介されています。

自分で書いた css-modules.d.ts を消し、どちらか一方だけにして試しました。src/vite-env.d.ts に1行を書いた場合も、tsconfig.json に "types": ["vite/client"] を足した場合も、npx tsc は終了コード 0 で終わりました。

ts
// src/vite-env.d.ts
/// <reference types="vite/client" />

宣言ファイルを置いても消えない2つの書き方

宣言ファイルがあっても、TypeScript に読み込まれていないか、新しいモジュールの宣言として扱われていないと、TS2307 は消えません。検証では次の2通りで、最初と同じメッセージが出たままでした。

include の外に置いた

css-modules.d.ts を src ではなく types フォルダーに移しました。tsconfig.json の include は ["src"] のままです。npx tsc --listFilesOnly で型チェックの対象になるファイルを一覧にすると(node_modules の中を除く)、src/main.ts だけで、types/css-modules.d.ts は入っていませんでした。

console
$ npx tsc --listFilesOnly | grep -v node_modules | sed 's#^/path/to/app/##'
src/main.ts

/path/to/app はプロジェクトの場所です。表示を短くするため、sed で取り除いています。

宣言ファイルは、include に合う場所に置きます。検証では、include を ["src", "types"] にすると、npx tsc は終了コード 0 で終わりました。ファイルを src に置く場合は、include を変える必要はありません。

宣言ファイルの先頭に export を書いた

型に名前を付けるため、宣言ファイルの先頭に export type を書いてみました。

ts
// src/css-modules.d.ts(これではエラーが消えない)
export type ClassMap = { readonly [key: string]: string }

declare module '*.module.css' {
  const classes: ClassMap
  export default classes
}

npx tsc を実行すると TS2307 が出ました。宣言そのもののエラーは出ません。先頭の export type の行を消して、classes の型を直接書いた形に戻すと、終了コード 0 で終わりました。

TypeScript のドキュメントによると、ファイルの一番外側に import か export があると、そのファイルはモジュールになります。すると declare module は新しいモジュールの宣言ではなく、既存のモジュールに型を足す書き方(module augmentation)として扱われます。型を別のファイルから持ってきたいときは、import を declare module の中に書けば、ファイルはモジュールにならない、とも書かれています。

import './global.css' には TS2882 が出る

変数に受け取らずに CSS を読み込む書き方(side-effect import)では、エラーの番号とメッセージが変わりました。宣言ファイルを置かずに import './global.css' だけを書いた src/main.ts で、npx tsc を実行した結果です。

console
$ npx tsc
src/main.ts(1,8): error TS2882: Cannot find module or type declarations for side-effect import of './global.css'.

tsconfig.json には何も足していませんが、TypeScript 7.0.2 ではこのチェックが働きました。noUncheckedSideEffectImports という設定を切る --noUncheckedSideEffectImports false を付けて npx tsc を実行すると、TS2882 は出ずに終了コード 0 で終わりました。TS2882 は、この設定によるエラーです。設定の説明では、CSS を読み込むときの対処として、中身のない declare module "*.css" {} を置く方法が紹介されています。

検証では、declare module '*.css' の1行だけを書いた src/css.d.ts を置くと、終了コード 0 で終わりました。css.d.ts の代わりに、/// <reference types="vite/client" /> の vite-env.d.ts を置いた場合も同じです。

​Posted by 86