css-loader

2.0.0 verified Sat Apr 25 auth: no javascript

CSS loader for webpack that interprets @import and url() like import/require() and resolves them. Current stable version is 7.1.4 (Feb 2026), with frequent releases. Key differentiator: it is the official webpack CSS loader, supporting CSS Modules, source maps, and advanced options like importLoaders and camelCase. Requires webpack 4+ as a peer dependency. Versions 6.x had a breaking change in 6.7.0 (named export default changes), and version 7.0.0 makes modules.namedExport true by default when esModule is enabled, requiring a migration from default import to namespace import.

Common errors

error Module not found: Error: Can't resolve 'style-loader' ↓

cause style-loader is not installed.

fix

Run npm install --save-dev style-loader

error CSS Modules: `composes` cannot be used with `@import` at the same time. ↓

cause Using `composes: ... from ...` inside a file that also has `@import` statements can conflict.

fix

Separate composes from @import in different files or avoid mixing them.

error Error: Cannot find module 'webpack' (required by css-loader) ↓

cause webpack is not installed or not in node_modules.

fix

Run npm install --save-dev webpack@^4 or install the appropriate version.

Warnings

breaking In version 7.0.0, modules.namedExport is true by default when esModule is enabled. This changes the import syntax from default to namespace import. ↓

fix Change `import styles from './style.css'` to `import * as styles from './style.css'` and update related code.

breaking In version 6.7.0, the default export for CSS Modules changed from an object with class names to the module itself, requiring use of the `default` export. ↓

fix Use `import styles from './style.css'` and access styles.myClass, or configure `modules.exportLocalsConvention` to get the old behavior.

deprecated The `localIdentName` option is deprecated in favor of `modules.localIdentName` and `modules.localIdentRegExp`. ↓

fix Use `modules.localIdentName` in the loader options.

gotcha When using `camelCase` option, class names are exported in camelCase, but the original kebab-case names may still be accessible depending on the configuration. ↓

fix Be consistent: either use only camelCase or only kebab-case imports to avoid confusion.

deprecated The `minimize` option is deprecated and removed; use `cssnano` or another minifier via webpack plugins. ↓

fix Remove `minimize` from css-loader options and use `CssMinimizerPlugin` in optimization.minimizer.

Install

npm install css-loader-1

yarn add css-loader-1

pnpm add css-loader-1

Imports

default import (CSS Module)
wrong
```
const styles = require('./style.css')
```
correct
```
import styles from './style.css'
```
In webpack with css-loader and style-loader, CSS is typically imported as a side-effect (no default export) unless CSS Modules are enabled. Using require() may work but is not recommended for ESM projects.
named import (CSS Modules with namedExport)
wrong
```
import styles from './style.css'
```
correct
```
import * as styles from './style.css'
```
Since css-loader v7.0.0 with esModule enabled, modules.namedExport defaults to true. Use namespace import to access class names; default import will not work.
type declaration for CSS Modules
wrong
```
require('./style.css')
```
correct
```
import styles from './style.css'; export default styles;
```
For TypeScript, you need a type declaration file (e.g., custom.d.ts) with 'declare module "*.module.css"' to avoid errors. The correct import style depends on your css-loader config.

Quickstart

Configures webpack to process CSS files with CSS Modules, loads them via style-loader, and uses the module's scoped class names.

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          { loader: 'style-loader' },
          { loader: 'css-loader', options: { modules: true, sourceMap: true } }
        ]
      }
    ]
  }
};

// app.js
import styles from './app.module.css';
const element = `<div class="${styles.root}">Hello</div>`;
document.body.innerHTML = element;