style-loader

4.0.0 verified Sat Apr 25 auth: no javascript

Webpack loader that injects CSS into the DOM by appending <style> or <link> tags. Version 4.0.0 (April 2024) requires webpack 5.27+ and Node.js 18.12+. Commonly paired with css-loader for development workflows. Supports multiple injection strategies (styleTag, singletonStyleTag, lazyStyleTag, linkTag) and can use CSS modules. Not recommended for production without additional configuration (e.g., ExtractTextPlugin). Maintained by the webpack-contrib team with regular updates.

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 to install the package.

error Error: 'style-loader' without 'css-loader' will not work ↓

cause Missing css-loader in the webpack config.

fix

Add 'css-loader' to the use array: use: ['style-loader', 'css-loader']

error TypeError: Cannot read properties of undefined (reading 'indexOf') ↓

cause Using an inline function for the 'insert' option in style-loader v4.

fix

Use a CSS selector string or a path to a module that exports the insert function.

Warnings

breaking Breaking change in v4: minimum supported webpack version is 5.27.0 and Node.js version is 18.12.0. ↓

fix Upgrade webpack to >=5.27.0 and Node.js to >=18.12.0.

deprecated The 'modules.namedExport' option was removed in v4. Use 'css-loader' options for CSS modules. ↓

fix Remove 'modules.namedExport' from style-loader options; configure CSS modules in css-loader instead.

gotcha style-loader is not safe for production by default; it injects styles dynamically which can cause performance issues and FOUC. ↓

fix Use MiniCssExtractPlugin for production builds instead of style-loader.

gotcha Source maps do not work with 'singletonStyleTag' injectType. ↓

fix Use 'styleTag' (default) or 'linkTag' if source maps are needed.

breaking In v4, the 'insert' option can only be a CSS selector or a path to a module exporting a function; inline function definitions are no longer allowed. ↓

fix If you used an inline function for 'insert', move it to a separate module and reference its path.

gotcha When using CSS modules with style-loader, all local class names are exported as named exports from the CSS file. ↓

fix Use `import * as styles from './styles.css'` and access classes via `styles['my-class']`.

Install

npm install style-loader

yarn add style-loader

pnpm add style-loader

Imports

style-loader

wrong

const styleLoader = require('style-loader'); // Not how loaders are typically imported

correct

// In webpack config: use 'style-loader' as a string in the 'use' array
module.exports = { module: { rules: [{ test: /\.css$/i, use: ['style-loader', 'css-loader'] }] } };

style-loader is used as a webpack loader, not imported directly in application code. Configure it in webpack.config.js.

use

wrong

use: [{ loader: 'style-loader' }, { loader: 'css-loader' }] // Correct object form, but wrong if using 'use' as an import

correct

use: ['style-loader', 'css-loader']

String form is shorthand; object form allows options. Both are correct.

options

wrong

use: ['style-loader', { loader: 'style-loader', options: { injectType: 'singletonStyleTag' } }] // Duplicate loader entry

correct

use: [{ loader: 'style-loader', options: { injectType: 'singletonStyleTag' } }]

Options are passed via the loader object. Cannot use string form when specifying options.

Quickstart

Basic webpack configuration using style-loader and css-loader to bundle CSS into a JavaScript bundle.

// webpack.config.js
const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    path: path.resolve(__dirname, 'dist'),
    filename: 'bundle.js'
  },
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader']
      }
    ]
  },
  mode: 'development'
};