How to Fix "Cannot Find Module or Type Declarations for Side-Effect Import" in TypeScript

If you're using TypeScript with Next.js or React and see an error like:

Cannot find module 'mapbox-gl/dist/mapbox-gl.css'
or its corresponding type declarations. (TS2882)

when importing a CSS file:

import 'mapbox-gl/dist/mapbox-gl.css'

you're likely running into TypeScript's handling of side-effect imports and the noUncheckedSideEffectImports option.

The confusing part is that the application may still work correctly. Next.js can find the CSS file, the browser loads the stylesheet, and the application builds successfully in some configurations—yet TypeScript or your IDE reports an error.

Fortunately, the fix is usually straightforward.

In this guide, you'll learn:

• What a side-effect import is in TypeScript
• Why TypeScript reports this CSS import error
• What noUncheckedSideEffectImports does
• How to fix TS2882 with declare module '*.css'
• How to configure global.d.ts
• The difference between wildcard and exact CSS module declarations
• Which approach is best for Next.js and React projects

What Causes the "Cannot Find Module or Type Declarations" Error?

Consider this common CSS import:

import 'mapbox-gl/dist/mapbox-gl.css'

TypeScript may report:

Cannot find module 'mapbox-gl/dist/mapbox-gl.css'
or its corresponding type declarations.

This doesn't necessarily mean that the CSS file doesn't exist.

In fact, if you've installed mapbox-gl, the file is normally located inside your node_modules directory:

node_modules/
└── mapbox-gl/
    ├── dist/
    │   ├── mapbox-gl.js
    │   └── mapbox-gl.css
    └── package.json

The problem is that TypeScript needs to understand the imported module, while CSS files don't contain TypeScript type declarations.

This becomes particularly noticeable when noUncheckedSideEffectImports is enabled.

What Is a Side-Effect Import in TypeScript?

A side-effect import is an import statement that doesn't import a specific value.

For example:

import './styles.css'

There is no variable being imported: