Native CSS

This guide walks through webpack's built-in CSS handling, enabled with experiments.css, and how to migrate an existing setup off css-loader, style-loader, and mini-css-extract-plugin.

Turn on native CSS support in your webpack configuration:

export default {
  experiments: {
    css: true,
  },
};

With this option enabled, webpack understands .css files as first-class modules — parsing @import and url(), extracting stylesheets, generating content hashes, and supporting CSS Modules — without css-loader, style-loader, or mini-css-extract-plugin.

Once the experiment is enabled, you can import .css files directly from JavaScript:

import './styles.css';

const element = document.createElement('h1');
element.textContent = 'Hello native CSS';
document.body.appendChild(element);

webpack processes the CSS and includes it in the build output.

Native CSS introduces four Rule.type values. Knowing which one applies is the key to migrating, because each maps to a different css-loader modules.mode:

The default rule webpack adds for /\.css$/i is css/auto, so *.module.css files become CSS Modules and everything else stays global — matching the most common css-loader configuration out of the box.

With css/auto, name a file *.module.css (or *.modules.css) to opt it into CSS Modules:

.button {
  background: #0d6efd;
  color: white;
  border: 0;
  border-radius: 4px;
  padding: 8px 12px;
}

You can tune CSS Modules behavior with parser and generator options — see All options with examples below:

export default {
  experiments: {
    css: true,
  },
  module: {
    parser: {
      'css/auto': {
        namedExports: true,
      },
    },
    generator: {
      'css/auto': {
        exportsConvention: 'camel-case-only',
        localIdentName: '[uniqueName]-[id]-[local]',
      },
    },
  },
};

Native CSS Modules understand the same authoring features as css-loader, so most stylesheets migrate unchanged:

• composes — compose one local class from another (including composes: foo from "./other.module.css"); the export resolves to the space-separated list of class names.
• @value — declare and import reusable values (@value primary: #1f6feb;, @value primary from "./vars.module.css").
• :export — expose arbitrary key/value pairs to JavaScript.
• :local() / :global() — switch scoping inline within any module type.

/* button.module.css */
@value brand: #1f6feb;

.base {
  padding: 8px 12px;
}
.primary {
  composes: base;
  background: brand;
}
:export {
  brandColor: brand;
}

A single CSS module can be emitted in four ways. The exportType parser option selects which one, and each replaces a different piece of the classic toolchain:

Set it globally per module type:

export default {
  experiments: { css: true },
  module: {
    parser: {
      'css/auto': {
        exportType: 'style',
      },
    },
  },
};

or per rule for a subset of files:

export default {
  experiments: { css: true },
  module: {
    rules: [
      {
        test: /\.css$/i,
        type: 'css/auto',
        parser: { exportType: 'style' },
      },
    ],
  },
};

Migrate one loader at a time — the sections below go in the order that keeps the build green at each step.

import MiniCssExtractPlugin from 'mini-css-extract-plugin';

export default {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: [MiniCssExtractPlugin.loader, 'css-loader'],
      },
    ],
  },
  plugins: [new MiniCssExtractPlugin()],
};

export default {
  experiments: {
    css: true,
  },
};

The built-in /\.css$/i → css/auto rule now handles .css imports. Remove your custom rule and plugin once the following sections confirm each option has an equivalent.

Native CSS extracts stylesheets and adds content hashes to them by default (exportType: "link"), so the plugin and its loader are no longer needed:

-import MiniCssExtractPlugin from "mini-css-extract-plugin";
-
 export default {
+  experiments: {
+    css: true,
+  },
-  module: {
-    rules: [
-      {
-        test: /\.css$/i,
-        use: [MiniCssExtractPlugin.loader, "css-loader"],
-      },
-    ],
-  },
-  plugins: [new MiniCssExtractPlugin()],
 };

Map the remaining plugin options:

export default {
  experiments: { css: true },
  output: {
    cssFilename: '[name].[contenthash].css',
    cssChunkFilename: '[id].[contenthash].css',
  },
};

Most css-loader options have a native counterpart under module.parser.css and module.generator.css. The common defaults (url, import, namedExports all on) already match a typical css-loader config, so many projects need no parser config at all.

For example, this css-loader CSS Modules config:

export default {
  module: {
    rules: [
      {
        test: /\.module\.css$/i,
        use: [
          {
            loader: 'css-loader',
            options: {
              modules: {
                localIdentName: '[local]-[hash:base64:6]',
                exportLocalsConvention: 'camel-case-only',
                namedExport: true,
              },
            },
          },
        ],
      },
    ],
  },
};

becomes:

export default {
  experiments: { css: true },
  module: {
    parser: {
      'css/auto': {
        namedExports: true,
      },
    },
    generator: {
      'css/auto': {
        localIdentName: '[local]-[hash:base64:6]',
        exportsConvention: 'camel-case-only',
      },
    },
  },
};

A few css-loader options work differently:

• getLocalIdent — instead of a custom function, native CSS drives naming through the localIdentName template, which also accepts a function.
• getJSON — the class-name mapping is exported by the CSS module itself and readable from the compilation's module graph, so a small plugin can serialize it to JSON when a framework needs the file on disk. For server-side rendering, you usually don't need it at all — see Server-side rendering.
• localIdentRegExp and filter-style url/import callbacks have no native equivalent; keep css-loader for the affected files, or exclude specific requests with IgnorePlugin.

If you used style-loader to inject styles at runtime instead of extracting a file, set exportType: "style":

export default {
  experiments: { css: true },
  module: {
    parser: {
      'css/auto': {
        exportType: 'style',
      },
    },
  },
};

This injects a <style> element from the webpack runtime, covering the default style-loader (injectType: "styleTag") use case. Scope it to a single rule if only some files should be injected while the rest are extracted:

export default {
  experiments: { css: true },
  module: {
    rules: [
      {
        test: /\.inline\.css$/i,
        type: 'css/auto',
        parser: { exportType: 'style' },
      },
    ],
  },
};

Notes on style-loader options: injectType: "linkTag" corresponds to the default exportType: "link" (extraction); attributes, insert, and styleTagTransform have no native equivalent — keep style-loader if you rely on them.

Native CSS replaces the CSS loaders, not preprocessor loaders. Keep the preprocessor loader in use and set the rule's type to css/auto so webpack treats the loader's output as CSS:

export default {
  experiments: { css: true },
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: ['postcss-loader', 'sass-loader'],
        type: 'css/auto',
      },
    ],
  },
};

sass-loader compiles to CSS, postcss-loader post-processes it, and native CSS handles extraction, url(), and CSS Modules from there. The same pattern works for less-loader, stylus-loader, and friends.

For SSR you typically build twice — a web bundle for the browser and a node bundle for the server — and the CSS Modules class names must match so the server-rendered markup hydrates cleanly on the client. This is what css-loader's getJSON was often used to round-trip; with native CSS you avoid the round-trip entirely by making localIdentName deterministic across targets.

Use a path-based template (no compilation-wide hash) so the same class name is produced on every target:

const common = {
  experiments: { css: true },
  module: {
    rules: [
      {
        test: /\.module\.css$/i,
        type: 'css/module',
        generator: {
          // `[file]__[local]` is stable across targets — no getJSON sync needed.
          localIdentName: '[file]__[local]',
        },
      },
    ],
  },
};

export default [
  { ...common, name: 'web', target: 'web' },
  { ...common, name: 'node', target: 'node' },
];

On a node target the CSS generator defaults to exportsOnly: true, so the server build exports only the class-name mapping and emits no stylesheet — exactly what an SSR renderer needs. The browser build still extracts the real CSS. If you prefer a single config, target: ["web", "node"] builds a universal bundle that runs in both environments.

Your JavaScript imports can stay the same:

import './styles.css';
import * as styles from './button.module.css';

Then check that:

• styles apply correctly in development,
• extracted .css files are emitted in production, and
• CSS Modules exports match your existing usage.

Configure options per module type under module.parser and module.generator. The keys are css, css/auto, css/global, and css/module; the examples below use css/auto since it backs the default rule.

All boolean parser options below default to true.

export default {
  experiments: { css: true },
  module: {
    parser: {
      'css/auto': {
        import: true,
        url: true,
        namedExports: true,
        exportType: 'link',
        pure: false,
        // Only rename @keyframes; leave @container / grid identifiers untouched.
        animation: true,
        container: false,
        grid: false,
      },
    },
  },
};

export default {
  experiments: { css: true },
  module: {
    generator: {
      'css/auto': {
        localIdentName: '[uniqueName]-[id]-[local]',
        exportsConvention: 'camel-case-only',
        esModule: true,
        exportsOnly: false,
        localIdentHashDigest: 'base64url',
        localIdentHashDigestLength: 6,
      },
    },
  },
};

exportsConvention also accepts a function returning a string or string[] — returning an array exports the local under several aliases, matching css-loader's behavior.

.primary {
  color: #1f6feb;
}
.large-text {
  font-size: 2rem;
}

export default {
  mode: 'production',
  experiments: { css: true },
  output: {
    cssFilename: 'css/[name].[contenthash].css',
    cssChunkFilename: 'css/[id].[contenthash].css',
  },
};

export default {
  experiments: { css: true },
  module: {
    parser: {
      'css/auto': {
        exportType: 'style',
      },
    },
  },
};

import sheet from './theme.css' with { type: 'css' };

document.adoptedStyleSheets = [sheet];

webpack resolves the with { type: "css" } import assertion to exportType: "css-style-sheet" automatically, giving you a CSSStyleSheet instance.

export default {
  experiments: { css: true },
  module: {
    parser: {
      'css/auto': {
        exportType: 'text',
      },
    },
  },
};

With the default css/auto rule, *.module.css is scoped and everything else is global — no extra config:

import './reset.css'; // global
import * as card from './card.module.css'; // scoped

Because experiments.css is explicitly experimental, treat it as opt-in and test carefully before rolling it out widely.

• APIs and behavior may still evolve before they become the default in webpack v6.
• A few loader options have no drop-in switch: css-loader's localIdentRegExp and filter callbacks, and style-loader's attributes / insert / styleTagTransform. Keep the loader for files that need them. (getLocalIdent maps to the localIdentName function form, and getJSON/SSR is covered by matching class names across targets.)
• importLoaders has no equivalent — loaders in the chain apply to @imported files automatically.
• If your project relies on advanced loader chains, validate each part before migrating fully.