Skip to content

Commit e2664e9

Browse files
evilebottnawievilebottnawi
authored
feat: new injectType option
BREAKING CHANGE: the `style-loader/url` and the `style-loader/useable` were removed in favor `injectType` option (look documentation). The `singleton` option was removed (look documentation about `injectType`).
1 parent c5992e4 commit e2664e9

32 files changed

+1199
-569
lines changed

‎README.md

Lines changed: 221 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -71,9 +71,42 @@ import style from './file.css';
7171
style.className === 'z849f98ca812';
7272
```
7373

74-
### `Useable`
74+
## Options
75+
76+
| Name | Type | Default | Description |
77+
| :--------------: | :------------------: | :--------: | :------------------------------------------------- |
78+
| **`injectType`** | `{String}` | `styleTag` | Allows to setup how styles will be injected in DOM |
79+
| **`attributes`** | `{Object}` | `{}` | Add custom attributes to tag |
80+
| **`insertAt`** | `{String\|Object}` | `bottom` | Inserts tag at the given position |
81+
| **`insertInto`** | `{String\|Function}` | `<head>` | Inserts tag into the given position |
82+
| **`base`** | `{Number}` | `true` | Set module ID base (DLLPlugin) |
83+
84+
### `injectType`
85+
86+
Type: `String`
87+
Default: `styleTag`
88+
89+
Allows to setup how styles will be injected in DOM.
7590

76-
The `style-loader` injects the styles lazily making them useable on-demand via `style.use()` / `style.unuse()`
91+
Possible values:
92+
93+
- `styleTag`
94+
- `singletonStyleTag`
95+
- `lazyStyleTag`
96+
- `lazySingletonStyleTag`
97+
- `linkTag`
98+
99+
When you `lazyStyleTag` or `lazySingletonStyleTag` value the `style-loader` injects the styles lazily making them useable on-demand via `style.use()` / `style.unuse()`.
100+
It is named `Reference Counter API`.
101+
102+
**component.js**
103+
104+
```js
105+
import style from './file.css';
106+
107+
style.use(); // = style.ref();
108+
style.unuse(); // = style.unref();
109+
```
77110

78111
By convention the `Reference Counter API` should be bound to `.useable.css` and the `.css` should be loaded with basic `style-loader` usage.(similar to other file types, i.e. `.useable.less` and `.less`).
79112

@@ -84,15 +117,19 @@ module.exports = {
84117
module: {
85118
rules: [
86119
{
87-
test: /\.css$/,
88-
exclude: /\.useable\.css$/,
120+
test: /\.css$/i,
121+
exclude: /\.useable\.css$/i,
89122
use: [{ loader: 'style-loader' }, { loader: 'css-loader' }],
90123
},
91124
{
92-
test: /\.useable\.css$/,
125+
test: /\.useable\.css$/i,
93126
use: [
94127
{
95-
loader: 'style-loader/useable',
128+
loader: 'style-loader',
129+
options: {
130+
// Can be `'lazyStyleTag'` or `'lazySingletonStyleTag'`
131+
injectType: 'lazyStyleTag',
132+
},
96133
},
97134
{ loader: 'css-loader' },
98135
],
@@ -102,27 +139,57 @@ module.exports = {
102139
};
103140
```
104141

105-
#### `Reference Counter API`
142+
Styles are not added on `import/require()`, but instead on call to `use`/`ref`. Styles are removed from page if `unuse`/`unref` is called exactly as often as `use`/`ref`.
106143

107-
**component.js**
144+
> ⚠️ Behavior is undefined when `unuse`/`unref` is called more often than `use`/`ref`. Don't do that.
145+
146+
#### `styleTag`
147+
148+
Injects styles in multiple `<style></style>`. It is **default** behaviour.
108149

109150
```js
110-
import style from './file.css';
151+
import './styles.css';
152+
```
111153

112-
style.use(); // = style.ref();
113-
style.unuse(); // = style.unref();
154+
**webpack.config.js**
155+
156+
```js
157+
module.exports = {
158+
module: {
159+
rules: [
160+
{
161+
test: /\.css$/i,
162+
use: [
163+
{ loader: 'style-loader', options: { injectType: 'styleTag' } },
164+
'css-loader',
165+
],
166+
},
167+
],
168+
},
169+
};
114170
```
115171

116-
Styles are not added on `import/require()`, but instead on call to `use`/`ref`. Styles are removed from page if `unuse`/`unref` is called exactly as often as `use`/`ref`.
172+
The loader inject styles like:
117173

118-
> ⚠️ Behavior is undefined when `unuse`/`unref` is called more often than `use`/`ref`. Don't do that.
174+
```html
175+
<style>
176+
.foo {
177+
color: red;
178+
}
179+
</style>
180+
<style>
181+
.bar {
182+
color: blue;
183+
}
184+
</style>
185+
```
119186

120-
### `Url`
187+
#### `singletonStyleTag`
121188

122-
It's also possible to add a URL `<link href="path/to/file.css" rel="stylesheet">` instead of inlining the CSS `{String}` with `<style></style>` tag.
189+
Injects styles in one `<style></style>`.
123190

124191
```js
125-
import url from 'file.css';
192+
import './styles.css';
126193
```
127194

128195
**webpack.config.js**
@@ -132,90 +199,159 @@ module.exports = {
132199
module: {
133200
rules: [
134201
{
135-
test: /\.css$/,
136-
use: [{ loader: 'style-loader/url' }, { loader: 'file-loader' }],
202+
test: /\.css$/i,
203+
use: [
204+
{
205+
loader: 'style-loader',
206+
options: { injectType: 'singletonStyleTag' },
207+
},
208+
'css-loader',
209+
],
137210
},
138211
],
139212
},
140213
};
141214
```
142215

216+
The loader inject styles like:
217+
143218
```html
144-
<link rel="stylesheet" href="path/to/file.css" />
219+
<style>
220+
.foo {
221+
color: red;
222+
}
223+
.bar {
224+
color: blue;
225+
}
226+
</style>
145227
```
146228

147-
## Options
229+
#### `lazyStyleTag`
148230

149-
| Name | Type | Default | Description |
150-
| :--------------: | :------------------: | :---------: | :------------------------------------------------------------------------------------------------------------------ |
151-
| **`base`** | `{Number}` | `true` | Set module ID base (DLLPlugin) |
152-
| **`attributes`** | `{Object}` | `{}` | Add custom attributes to `<style></style>` |
153-
| **`insertAt`** | `{String\|Object}` | `bottom` | Inserts `<style></style>` at the given position |
154-
| **`insertInto`** | `{String\|Function}` | `<head>` | Inserts `<style></style>` into the given position |
155-
| **`singleton`** | `{Boolean}` | `undefined` | Reuses a single `<style></style>` element, instead of adding/removing individual elements for each required module. |
231+
Injects styles in multiple `<style></style>` on demand (documentation above).
156232

157-
### `base`
233+
```js
234+
import styles from './styles.css';
158235

159-
This setting is primarily used as a workaround for [css clashes](https://github.com/webpack-contrib/style-loader/issues/163) when using one or more [DllPlugin](https://robertknight.github.io/posts/webpack-dll-plugins/)'s. `base` allows you to prevent either the _app_'s css (or _DllPlugin2_'s css) from overwriting _DllPlugin1_'s css by specifying a css module id base which is greater than the range used by _DllPlugin1_ e.g.:
236+
styles.use();
237+
```
160238

161-
**webpack.dll1.config.js**
239+
**webpack.config.js**
162240

163241
```js
164242
module.exports = {
165243
module: {
166244
rules: [
167245
{
168-
test: /\.css$/i,
246+
test: /\.useable\.css$/i,
169247
use: [
170-
{
171-
loader: 'style-loader',
172-
},
173-
{ loader: 'css-loader' },
248+
{ loader: 'style-loader', options: { injectType: 'lazyStyleTag' } },
249+
'css-loader',
174250
],
175251
},
176252
],
177253
},
178254
};
179255
```
180256

181-
**webpack.dll2.config.js**
257+
The loader inject styles like:
258+
259+
```html
260+
<style>
261+
.foo {
262+
color: red;
263+
}
264+
</style>
265+
<style>
266+
.bar {
267+
color: blue;
268+
}
269+
</style>
270+
```
271+
272+
#### `lazySingletonStyleTag`
273+
274+
Injects styles in one `<style></style>` on demand (documentation above).
275+
276+
```js
277+
import styles from './styles.css';
278+
279+
styles.use();
280+
```
281+
282+
**webpack.config.js**
182283

183284
```js
184285
module.exports = {
185286
module: {
186287
rules: [
187288
{
188-
test: /\.css$/,
289+
test: /\.useable\.css$/i,
189290
use: [
190-
{ loader: 'style-loader', options: { base: 1000 } },
191-
{ loader: 'css-loader' },
291+
{
292+
loader: 'style-loader',
293+
options: { injectType: 'lazySingletonStyleTag' },
294+
},
295+
'css-loader',
192296
],
193297
},
194298
],
195299
},
196300
};
197301
```
198302

199-
**webpack.app.config.js**
303+
The loader generate this:
304+
305+
```html
306+
<style>
307+
.foo {
308+
color: red;
309+
}
310+
.bar {
311+
color: blue;
312+
}
313+
</style>
314+
```
315+
316+
#### `linkTag`
317+
318+
Injects styles in multiple `<link rel="stylesheet" href="path/to/file.css">` .
319+
320+
```js
321+
import './styles.css';
322+
import './other-styles.css';
323+
```
324+
325+
**webpack.config.js**
200326

201327
```js
202328
module.exports = {
203329
module: {
204330
rules: [
205331
{
206-
test: /\.css$/,
332+
test: /\.css$/i,
207333
use: [
208-
{ loader: 'style-loader', options: { base: 2000 } },
209-
{ loader: 'css-loader' },
334+
{ loader: 'style-loader', options: { injectType: 'linkTag' } },
335+
{ loader: 'file-loader' },
210336
],
211337
},
212338
],
213339
},
214340
};
215341
```
216342

343+
The loader generate this:
344+
345+
```html
346+
<link rel="stylesheet" href="path/to/style.css" />
347+
<link rel="stylesheet" href="path/to/other-styles.css" />
348+
```
349+
217350
### `attributes`
218351

352+
Type: `Object`
353+
Default: `{}`
354+
219355
If defined, style-loader will attach given attributes with their values on `<style>` / `<link>` element.
220356

221357
**component.js**
@@ -231,7 +367,7 @@ module.exports = {
231367
module: {
232368
rules: [
233369
{
234-
test: /\.css$/,
370+
test: /\.css$/i,
235371
use: [
236372
{ loader: 'style-loader', options: { attributes: { id: 'id' } } },
237373
{ loader: 'css-loader' },
@@ -354,13 +490,49 @@ module.exports = {
354490
};
355491
```
356492

357-
### `singleton`
493+
### `base`
358494

359-
If defined, the style-loader will reuse a single `<style></style>` element, instead of adding/removing individual elements for each required module.
495+
This setting is primarily used as a workaround for [css clashes](https://github.com/webpack-contrib/style-loader/issues/163) when using one or more [DllPlugin](https://robertknight.github.io/posts/webpack-dll-plugins/)'s. `base` allows you to prevent either the _app_'s css (or _DllPlugin2_'s css) from overwriting _DllPlugin1_'s css by specifying a css module id base which is greater than the range used by _DllPlugin1_ e.g.:
360496

361-
> ℹ️ This option is on by default in IE9, which has strict limitations on the number of style tags allowed on a page. You can enable or disable it with the singleton option.
497+
**webpack.dll1.config.js**
362498

363-
**webpack.config.js**
499+
```js
500+
module.exports = {
501+
module: {
502+
rules: [
503+
{
504+
test: /\.css$/i,
505+
use: [
506+
{
507+
loader: 'style-loader',
508+
},
509+
{ loader: 'css-loader' },
510+
],
511+
},
512+
],
513+
},
514+
};
515+
```
516+
517+
**webpack.dll2.config.js**
518+
519+
```js
520+
module.exports = {
521+
module: {
522+
rules: [
523+
{
524+
test: /\.css$/i,
525+
use: [
526+
{ loader: 'style-loader', options: { base: 1000 } },
527+
{ loader: 'css-loader' },
528+
],
529+
},
530+
],
531+
},
532+
};
533+
```
534+
535+
**webpack.app.config.js**
364536

365537
```js
366538
module.exports = {
@@ -369,7 +541,7 @@ module.exports = {
369541
{
370542
test: /\.css$/i,
371543
use: [
372-
{ loader: 'style-loader', options: { singleton: true } },
544+
{ loader: 'style-loader', options: { base: 2000 } },
373545
{ loader: 'css-loader' },
374546
],
375547
},

0 commit comments

Comments
 (0)