css-loader

7.1.4 verified Sat Apr 25 auth: no javascript

The css-loader is a webpack loader that interprets @import and url() in CSS files like JavaScript import/require, resolving them into modules. Current stable version is 7.1.4, released in February 2026, with active development and frequent minor releases. It supports CSS Modules, source maps, and various import/url resolution strategies. Unlike other CSS loaders, it is designed specifically for webpack 5+ and integrates deeply with webpack's module system. Peer dependencies include webpack ^5.27.0 and optional @rspack/core. Key differentiators include fine-grained options for url/import filtering, CSS Modules with named exports, and compatibility with modern CSS features like nesting and @scope.

Common errors

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. ↓

cause Missing rule for CSS files in webpack config.

fix

Add a rule with css-loader in module.rules: { test: /\.css$/, use: ['style-loader', 'css-loader'] }

error Cannot find module 'css-loader' ↓

cause css-loader not installed as dev dependency.

fix

Run: npm install --save-dev css-loader

error Error: 'default' is not exported by .../styles.module.css ↓

cause Using default import with named exports enabled (v7+ default).

fix

Use import * as styles from './styles.module.css'

Warnings

breaking In v7.0.0, modules.namedExport defaults to true when esModule is true. This changes how CSS classes are imported: previously default import worked, now require namespace import. ↓

fix Use import * as styles from './styles.module.css' instead of import styles from './styles.module.css'.

deprecated String values for `modules.exportLocalsConvention` are deprecated in favor of object syntax. ↓

fix Use { exportLocalsConvention: { camelCase: true } } instead of 'camelCase'.

gotcha Absolute URLs in url() are resolved relative to server root since v4.0.0, which may break if your server root is different from project root. ↓

fix Use a custom filter or set url: false to prevent resolution of absolute paths.

gotcha The `url()` function with `~` prefix to resolve node_modules only works if the value starts with `~`. Common mistake: forgetting tilde for aliased paths. ↓

fix Use url('~module/image.png') instead of url('module/image.png').

breaking Node.js >= 18.12.0 is required starting from v7. Older Node versions will cause errors. ↓

fix Upgrade Node.js to version 18.12.0 or later.

Install

npm install css-loader

yarn add css-loader

pnpm add css-loader

Imports

css-loader
wrong
```
module.exports = { module: { rules: [ { test: /\.css$/i, use: 'css-loader' } ] } }
```
correct
```
module.exports = { module: { rules: [ { test: /\.css$/i, use: ['style-loader', 'css-loader'] } ] } }
```
css-loader is not imported directly in JavaScript; it is configured in webpack config as a loader. Common mistake: using string instead of array when combining with style-loader.
default
wrong
```
import { default as styles } from './styles.module.css';
```
correct
```
import styles from './styles.module.css';
```
Since v7.0.0, when esModule is enabled, named exports are default. Use default import for entire CSS module object.
named
wrong
```
import styles from './styles.module.css';
```
correct
```
import * as styles from './styles.module.css';
```
Since v7.0.0, modules.namedExport defaults to true when esModule is true. Use namespace import to access individual class names.

Quickstart

Shows basic webpack configuration for CSS Modules with latest named export syntax (v7+).

// file.js
import * as styles from './styles.module.css';

console.log(styles.myClass);

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