diff --git a/pages/guides/contributing/writers-guide.md b/pages/guides/contributing/writers-guide.md index 9cf9871b..0ffb8409 100644 --- a/pages/guides/contributing/writers-guide.md +++ b/pages/guides/contributing/writers-guide.md @@ -1,6 +1,6 @@ --- title: Writer's Guide -authors: avivkeller +authors: avivkeller,alexander-akait --- # Writer's Guide diff --git a/pages/guides/contributing/writing-a-plugin.md b/pages/guides/contributing/writing-a-plugin.md index 9e7c9761..15c7903c 100644 --- a/pages/guides/contributing/writing-a-plugin.md +++ b/pages/guides/contributing/writing-a-plugin.md @@ -1,6 +1,6 @@ --- title: Writing a Plugin -authors: slavafomin,tbroadley,nveenjain,iamakulov,byzyk,franjohn21,EugeneHlushko,snitin315,rahul3v,jamesgeorge007 +authors: slavafomin,tbroadley,nveenjain,iamakulov,byzyk,franjohn21,EugeneHlushko,snitin315,rahul3v,jamesgeorge007,bjohansebas --- # Writing a Plugin diff --git a/pages/guides/core-workflows/production.md b/pages/guides/core-workflows/production.md index 0e2a257c..e24458bc 100644 --- a/pages/guides/core-workflows/production.md +++ b/pages/guides/core-workflows/production.md @@ -1,6 +1,6 @@ --- title: Production -authors: henriquea,rajagopal4890,makuzaverite,markerikson,simon04,kisnows,chrisVillanueva,swapnilmishra,bring2dip,redian,skipjack,xgqfrms,kelset,xgirma,mehrdaad,SevenOutman,AnayaDesign,wizardofhogwarts,aholzner,EugeneHlushko,snitin315,Brennvo,ThierryRakotomanana,avivkeller +authors: henriquea,rajagopal4890,makuzaverite,markerikson,simon04,kisnows,chrisVillanueva,swapnilmishra,bring2dip,redian,skipjack,xgqfrms,kelset,xgirma,mehrdaad,SevenOutman,AnayaDesign,wizardofhogwarts,aholzner,EugeneHlushko,snitin315,Brennvo,ThierryRakotomanana,avivkeller,alexander-akait --- # Production diff --git a/pages/guides/getting-started/concepts/targets.md b/pages/guides/getting-started/concepts/targets.md index 2b89d292..e75e0b27 100644 --- a/pages/guides/getting-started/concepts/targets.md +++ b/pages/guides/getting-started/concepts/targets.md @@ -1,6 +1,6 @@ --- title: Targets -authors: TheLarkInn,rouzbeh84,johnstew,srilman,byzyk,EugeneHlushko,avivkeller +authors: TheLarkInn,rouzbeh84,johnstew,srilman,byzyk,EugeneHlushko,avivkeller,alexander-akait --- # Targets diff --git a/pages/guides/getting-started/index.md b/pages/guides/getting-started/index.md index 879c73b8..c448ea42 100644 --- a/pages/guides/getting-started/index.md +++ b/pages/guides/getting-started/index.md @@ -1,6 +1,6 @@ --- title: Getting Started -authors: bebraw,varunjayaraman,cntanglijun,chrisVillanueva,johnstew,simon04,aaronang,TheDutchCoder,sudarsangp,Vanguard90,chenxsan,EugeneHlushko,ATGardner,ayvarot,bjarki,ztomasze,Spiral90210,byzyk,wizardofhogwarts,myshov,anshumanv,d3lm,snitin315,Etheryen,zowiebeha,avivkeller +authors: bebraw,varunjayaraman,cntanglijun,chrisVillanueva,johnstew,simon04,aaronang,TheDutchCoder,sudarsangp,Vanguard90,chenxsan,EugeneHlushko,ATGardner,ayvarot,bjarki,ztomasze,Spiral90210,byzyk,wizardofhogwarts,myshov,anshumanv,d3lm,snitin315,Etheryen,zowiebeha,avivkeller,alexander-akait --- # Getting Started diff --git a/pages/guides/modern-web/native-css.md b/pages/guides/modern-web/native-css.md index b5f40b7b..72b2302f 100644 --- a/pages/guides/modern-web/native-css.md +++ b/pages/guides/modern-web/native-css.md @@ -1,11 +1,11 @@ --- title: Native CSS -authors: phoekerson,avivkeller +authors: phoekerson,avivkeller,alexander-akait --- # Native CSS -This guide walks through webpack's built-in CSS handling, enabled with `experiments.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`. > [!WARNING] > `experiments.css` is still experimental. It is expected to become the default in webpack v6, but its behavior may continue to change while development is ongoing. @@ -22,7 +22,7 @@ export default { }; ``` -With this option enabled, webpack can process CSS without `css-loader` or `mini-css-extract-plugin` for the basic flow. +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`. ## Importing CSS @@ -44,12 +44,22 @@ h1 { webpack processes the CSS and includes it in the build output. -## CSS Modules +## CSS module types + +Native CSS introduces four [`Rule.type`](/docs/api/options#modulerules) values. Knowing which one applies is the key to migrating, because each maps to a different `css-loader` `modules.mode`: + +| Type | Scoping | `css-loader` equivalent | +| ------------ | ------------------------------------------------------------------------------- | ------------------------ | +| `css` | Global, no CSS Modules parsing | `modules: false` | +| `css/global` | Global selectors, but `:local()` is honored | `modules.mode: 'global'` | +| `css/module` | Local by default, `:global()` escapes to global | `modules.mode: 'local'` | +| `css/auto` | Picks `css/module` for `*.module.css` / `*.modules.css`, otherwise `css/global` | `modules.auto: true` | + +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. -Native CSS support also covers CSS Modules. The recommended approach is to: +## CSS Modules -- keep `type: "css/auto"` for mixed CSS handling, and -- use the `.module.css` (or `.modules.css`) naming convention for CSS Modules files. +With `css/auto`, name a file `*.module.css` (or `*.modules.css`) to opt it into CSS Modules: ```css displayName="src/button.module.css" .button { @@ -70,10 +80,10 @@ button.textContent = 'Click me'; document.body.appendChild(button); ``` -> [!TIP] -> CSS Modules class names are exported, and named exports are enabled for CSS Modules by default. +> [!NOTE] +> By default [`namedExports`](/docs/api/options#moduleparsercss) is enabled, so import the locals as a namespace (`import * as styles`) or by name (`import { button } from "./button.module.css"`). Set it to `false` to keep the classic default-import object. -You can tune CSS Modules behavior with parser and generator options: +You can tune CSS Modules behavior with parser and generator options — see [All options with examples](#all-options-with-examples) below: ```js displayName="webpack.config.js" export default { @@ -82,12 +92,12 @@ export default { }, module: { parser: { - 'css/module': { + 'css/auto': { namedExports: true, }, }, generator: { - 'css/module': { + 'css/auto': { exportsConvention: 'camel-case-only', localIdentName: '[uniqueName]-[id]-[local]', }, @@ -96,30 +106,95 @@ export default { }; ``` -## Production builds +### Supported CSS Modules features -With `experiments.css: true`, webpack performs native CSS extraction and applies content hashing to CSS assets in production builds. +Native CSS Modules understand the same authoring features as `css-loader`, so most stylesheets migrate unchanged: -Compared with the classic setup: +- **`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. -- Traditional approach: `css-loader` plus `mini-css-extract-plugin`. -- Native approach: `experiments.css` with built-in extraction behavior. +```css +/* button.module.css */ +@value brand: #1f6feb; -This reduces configuration and keeps the CSS pipeline closer to webpack's core features. +.base { + padding: 8px 12px; +} +.primary { + composes: base; + background: brand; +} +:export { + brandColor: brand; +} +``` -## Experimental status and known limitations +## Output modes (`exportType`) -Because `experiments.css` is explicitly experimental, treat it as opt-in and test carefully before rolling it out widely. +A single CSS module can be emitted in four ways. The [`exportType`](/docs/api/options#moduleparsercss) parser option selects which one, and each replaces a different piece of the classic toolchain: -Keep the following points in mind: +| `exportType` | Behavior | Replaces | +| -------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| `"link"` _(default)_ | Extracts a `.css` file, loaded via `` | `mini-css-extract-plugin` | +| `"style"` | Injects a `