scoped-css-webpack-plugin 🎨

A zero-configuration solution for scoped CSS in React applications, providing automatic style encapsulation similar to Vue's scoped styles.

In this package, you can write your style in a single file, import the style in the component, and the style will only work on the imported file, and the style imported by the entry file will be effective globally.

✨ Features

• Automatic Scoping
  Automatically generates unique scope IDs for components
• CSS Isolation
  Prevents style leakage between components
• Framework Agnostic
  Works with any CSS preprocessor (Sass/Less/Stylus)
• Production-Ready
  Supports CSS extraction and optimization
• Zero Runtime
  All processing happens at build time

Install

1npm install scoped-css-webpack-plugin --save-dev
2# or
3yarn add scoped-css-webpack-plugin -D

🚀 Basic Usage

Webpack Configuration

1// webpack.config.js
2const path = require('path')
3const {BabelScopedPlugin, PostcssScopedPlugin} = require('scoped-css-webpack-plugin')
4
5
6module.exports = {
7  module: {
8    rules: [
9      {
10        test: /\.jsx?$/,
11        use: [
12          {
13            loader: 'babel-loader',
14            options: {
15              // if you are using in a react project
16              presets: ['@babel/preset-react'],
17              plugins: [
18                [
19                  BabelScopedPlugin,
20                  {entryFiles: [path.resolve(__dirname, './src/main.js')]}
21                ]
22              ]
23            }
24          }
25        ]
26      },
27      {
28        test: /\.css$/,
29        use: [
30          'style-loader',
31          'css-loader',
32          {
33            loader: 'postcss-loader',
34            options: {
35              postcssOptions: {
36                plugins: [
37                  [
38                    new PostcssScopedPlugin()
39                  ]
40                ]
41              }
42            }
43          },
44          'scoped-css-webpack-plugin/lib/loader'
45        ]
46      }
47    ]
48  }
49}

Component css file

1.my-component {
2  padding: 10px 20px;
3  background-color: blue;
4}
5
6.my-component-title {
7  color: red;
8}

Component JSX file

1// you must add the suffix like .css .less .sass
2import './mycomponent.css'
3
4function MyComponent() {
5  return (
6    <div className='my-component'>
7      <h1 className='my-component-title'>Hello World</h1>
8    </div>
9  );
10}

🔧 Configuration Options

Babel Plugin Options

1const {BabelScopedPlugin} = require('scoped-css-webpack-plugin')
2
3{
4  plugins: [
5    [BabelScopedPlugin, {
6      entryFiles: [path.resolve(__dirname, './src/main.js')], // Required: entry files array
7      prefix: 'data-scope-',         // Scope ID prefix
8      fileSuffix: [                  // File extensions to process
9        '.css',
10        '.scss',
11        '.sass',
12        '.less'
13      ],
14      generateScopeId: (filePath) =>  // Custom ID generator
15        `scope-${md5(filePath).slice(0,8)}`
16    }]
17  ]
18}

PostCSS Plugin Options

1const {PostcssScopedPlugin} = require('scoped-css-webpack-plugin')
2
3{
4  plugins: [
5    [PostcssScopedPlugin, {
6      includeTypes: ['class', 'id', 'tag'],  // Selector types to scope
7      excludeTypes: ['pseudo', 'comment'],   // Selector types to exclude
8      commentPrefix: '@scope-id'             // Comment marker prefix
9    }]
10  ]
11}

🎯 Advanced Features

Custom Scope Formatting

1const {BabelScopedPlugin} = require('scoped-css-webpack-plugin')
2
3{
4  plugins: [
5    [BabelScopedPlugin, {
6      entryFiles: [path.resolve(__dirname, './src/main.js')], // Required: entry files array
7      prefix: 'data-scope-',         // Scope ID prefix
8      fileSuffix: [                  // File extensions to process
9        '.css',
10        '.scss',
11        '.sass',
12        '.less'
13      ],
14      generateScopeId: (filePath) =>  // Custom ID generator
15        `scope-${md5(filePath).slice(0,8)}`
16    }]
17  ]
18}

Global Styles

Mark entry files in Babel config:

1// webpack.config.js
2const {BabelScopedPlugin} = require('scoped-css-webpack-plugin')
3
4module.exports = {
5  module: {
6    rules: [
7      {
8        test: /\.jsx?$/,
9        use: [
10          {
11            loader: 'babel-loader',
12            options: {
13              // if you are in a react project
14              presets: ['@babel/preset-react'],
15              plugins: [
16                [
17                  BabelScopedPlugin,
18                  {
19                    entryFiles: [path.resolve(__dirname, './src/main.js')],
20                    generateScopeId: (filePath) =>  // Custom ID generator
21                      `scope-${md5(filePath).slice(0,8)}`
22                  }
23                ]
24              ]
25            }
26          }
27        ]
28      },
29      // ...
30    ]
31  }
32}

Scoped JSX

Input:

1function MyComponent() {
2  return (
3    <div>
4      <h1>Hello World</h1>
5    </div>
6  );
7}

Output:

1function MyComponent() {
2  return (
3    <div data-scope-abc123>
4      <h1 data-scope-abc123>Hello World</h1>
5    </div>
6  );
7}

📄 Generated CSS

Input:

1/* @scope-id: data-scope-abc123 */
2.container {
3  padding: 20px;
4}

Output:

1.container[data-scope-abc123] {
2  padding: 20px;
3}