Auto CSS Modules Webpack Plugin

1.1.1 verified Sat Apr 25 auth: no javascript

Automatically detects import or require statements for CSS files and adds a query parameter to mark them as CSS Modules in webpack. Current stable version is 1.1.1, with npm package last updated in March 2023. The plugin works by analyzing the AST during webpack's parse phase, converting statements like `import styles from './index.css'` to `import styles from './index.css?modules'`. Supports default extensions: .css, .less, .sass, .scss, .stylus, .styl. Designed for webpack 4 (>=4.46.0) and 5 (>=5.20.0). Key differentiator: avoids manual configuration of CSS Modules per file by automating the detection based on variable assignment.

Common errors

error Cannot find module 'auto-css-modules-webpack-plugin' ↓

cause Package not installed or missing from node_modules.

fix

Run npm install --save-dev auto-css-modules-webpack-plugin.

error TypeError: AutoCSSModulesWebpackPlugin is not a constructor ↓

cause Using import statement instead of require, or missing .default.

fix

Use const AutoCSSModulesWebpackPlugin = require('auto-css-modules-webpack-plugin');.

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type ↓

cause css-loader not configured correctly or oneOf rules missing.

fix

Add 'style-loader' and 'css-loader' to the webpack config as shown in quickstart.

Warnings

gotcha Plugin cannot be used with webpack <4.46.0 or <5.20.0 due to peer dependency range. ↓

fix Upgrade webpack to version 4.46.0+ or 5.20.0+.

gotcha Default extname list is fixed and cannot be overwritten; extraExtnames appends to the list but does not replace defaults. ↓

fix If you need to exclude a default extension, consider a custom webpack rule instead.

deprecated The package is low maintenance; last update March 2023. May not support future webpack versions. ↓

fix Consider alternatives like @umijs/babel-plugin-auto-css-modules for newer setups.

Install

npm install auto-css-modules-webpack-plugin

yarn add auto-css-modules-webpack-plugin

pnpm add auto-css-modules-webpack-plugin

Imports

AutoCSSModulesWebpackPlugin

wrong

import AutoCSSModulesWebpackPlugin from 'auto-css-modules-webpack-plugin'

correct

const AutoCSSModulesWebpackPlugin = require('auto-css-modules-webpack-plugin')

Package does not ship ESM; CommonJS require is mandatory.

AutoCSSModulesWebpackPlugin

wrong

const AutoCSSModulesWebpackPlugin = require('auto-css-modules-webpack-plugin')

correct

const AutoCSSModulesWebpackPlugin = require('auto-css-modules-webpack-plugin').default

If using TypeScript with esModuleInterop, direct require works; otherwise .default may be needed. Check your setup.

webpack configuration

wrong

module.exports = { plugins: [new AutoCSSModulesWebpackPlugin()] }

correct

const AutoCSSModulesWebpackPlugin = require('auto-css-modules-webpack-plugin'); module.exports = { plugins: [new AutoCSSModulesWebpackPlugin({ queryFlag: 'modules', extraExtnames: [] })] }

Default options work; but extraExtnames must be provided if using non-standard extensions beyond defaults.

Quickstart

Webpack config with css-loader oneOf rules: CSS files with ?modules query get CSS Modules enabled, others treated as global CSS. Plugin auto-adds ?modules to imports.

const AutoCSSModulesWebpackPlugin = require('auto-css-modules-webpack-plugin');
const path = require('path');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js' },
  module: {
    rules: [
      {
        test: /\.css$/i,
        oneOf: [
          {
            resourceQuery: /modules/,
            use: ['style-loader', { loader: 'css-loader', options: { modules: { localIdentName: '[name]__[local]--[hash:base64:5]' } } }]
          },
          { use: ['style-loader', { loader: 'css-loader', options: {} }] }
        ]
      }
    ]
  },
  plugins: [new AutoCSSModulesWebpackPlugin({ queryFlag: 'modules', extraExtnames: [] })]
};