Skip to content

Commit 2213920

Browse files
committed
docs(guides): expand native css migration with loader option mapping
1 parent c8122cb commit 2213920

File tree

1 file changed

+102
-3
lines changed

1 file changed

+102
-3
lines changed

src/content/guides/native-css.mdx

Lines changed: 102 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,31 @@ document.body.appendChild(button);
7878

7979
T> CSS Modules class names are exported. By default, named exports are enabled for CSS modules.
8080

81+
You can customize CSS Modules behavior using parser and generator options:
82+
83+
**webpack.config.js**
84+
85+
```js
86+
export default {
87+
experiments: {
88+
css: true,
89+
},
90+
module: {
91+
parser: {
92+
"css/module": {
93+
namedExports: true,
94+
},
95+
},
96+
generator: {
97+
"css/module": {
98+
exportsConvention: "camel-case-only",
99+
localIdentName: "[uniqueName]-[id]-[local]",
100+
},
101+
},
102+
},
103+
};
104+
```
105+
81106
## Production Build
82107

83108
With `experiments.css: true`, webpack provides native CSS extraction and content hashing for CSS assets in production builds.
@@ -101,7 +126,7 @@ Known points to keep in mind:
101126

102127
## Migration Guide
103128

104-
If you currently use `css-loader` and `mini-css-extract-plugin`, migrate in small steps.
129+
If you currently use `css-loader`, `mini-css-extract-plugin`, and `style-loader`, migrate in small steps.
105130

106131
### 1) Start from a classic setup
107132

@@ -135,7 +160,81 @@ export default {
135160
};
136161
```
137162

138-
### 3) Keep imports unchanged
163+
### 3) Migrate `css-loader` options first
164+
165+
Most CSS Modules-related options should move to native parser/generator config.
166+
167+
**webpack.config.js**
168+
169+
```js
170+
export default {
171+
experiments: {
172+
css: true,
173+
},
174+
module: {
175+
parser: {
176+
css: {
177+
import: true,
178+
url: true,
179+
},
180+
"css/module": {
181+
namedExports: true,
182+
},
183+
},
184+
generator: {
185+
"css/module": {
186+
exportsConvention: "camel-case-only",
187+
localIdentName: "[uniqueName]-[id]-[local]",
188+
},
189+
},
190+
},
191+
};
192+
```
193+
194+
Notes:
195+
196+
- `import` and `url` are native parser switches for CSS handling.
197+
- `namedExports` controls CSS Modules exports behavior.
198+
- `exportsConvention` and `localIdentName` provide class export/name shaping.
199+
- `css-loader` filter-style options are not available as direct equivalents; use webpack mechanisms such as `IgnorePlugin` when needed.
200+
201+
### 4) Replace `mini-css-extract-plugin`
202+
203+
When `experiments.css` is enabled, webpack provides native CSS extraction and content hash handling for CSS output files.
204+
205+
That means you can remove:
206+
207+
- `MiniCssExtractPlugin.loader` from `module.rules`,
208+
- the `new MiniCssExtractPlugin()` plugin instance.
209+
210+
### 5) Replace `style-loader` with `exportType: "style"`
211+
212+
If you used `style-loader` for runtime style injection, use CSS module parser `exportType: "style"`:
213+
214+
**webpack.config.js**
215+
216+
```js
217+
export default {
218+
experiments: {
219+
css: true,
220+
},
221+
module: {
222+
rules: [
223+
{
224+
test: /\.css$/i,
225+
type: "css/module",
226+
parser: {
227+
exportType: "style",
228+
},
229+
},
230+
],
231+
},
232+
};
233+
```
234+
235+
This mode injects a `<style>` element from the webpack runtime and covers the typical `style-loader` use case.
236+
237+
### 6) Keep imports unchanged
139238

140239
Your JS imports can stay the same:
141240

@@ -144,7 +243,7 @@ import "./styles.css";
144243
import * as styles from "./button.module.css";
145244
```
146245

147-
### 4) Validate output in development and production
246+
### 7) Validate output in development and production
148247

149248
Check that:
150249

0 commit comments

Comments
 (0)