1266 lines
27 KiB
Markdown
1266 lines
27 KiB
Markdown
<div align="center">
|
||
<a href="https://github.com/webpack/webpack">
|
||
<img width="200" height="200"
|
||
src="https://webpack.js.org/assets/icon-square-big.svg">
|
||
</a>
|
||
<h1>Style Loader</h1>
|
||
</div>
|
||
|
||
[![npm][npm]][npm-url]
|
||
[![node][node]][node-url]
|
||
[![tests][tests]][tests-url]
|
||
[![coverage][cover]][cover-url]
|
||
[![discussion][discussion]][discussion-url]
|
||
[![size][size]][size-url]
|
||
|
||
# style-loader
|
||
|
||
Inject CSS into the DOM.
|
||
|
||
## Getting Started
|
||
|
||
To begin, you'll need to install `style-loader`:
|
||
|
||
```console
|
||
npm install --save-dev style-loader
|
||
```
|
||
|
||
or
|
||
|
||
```console
|
||
yarn add -D style-loader
|
||
```
|
||
|
||
or
|
||
|
||
```console
|
||
pnpm add -D style-loader
|
||
```
|
||
|
||
It's recommended to combine `style-loader` with the [`css-loader`](https://github.com/webpack-contrib/css-loader)
|
||
|
||
Then add the loader to your `webpack` config. For example:
|
||
|
||
**style.css**
|
||
|
||
```css
|
||
body {
|
||
background: green;
|
||
}
|
||
```
|
||
|
||
**component.js**
|
||
|
||
```js
|
||
import "./style.css";
|
||
```
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: ["style-loader", "css-loader"],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
## Security Warning
|
||
|
||
This loader is primarily meant for development. The default settings are not safe for production environments. See the [recommended example configuration](#recommended) and the section on [nonces](#nonce) for details.
|
||
|
||
## Options
|
||
|
||
- [**`injectType`**](#injecttype)
|
||
- [**`attributes`**](#attributes)
|
||
- [**`insert`**](#insert)
|
||
- [**`styleTagTransform`**](#styleTagTransform)
|
||
- [**`base`**](#base)
|
||
- [**`esModule`**](#esmodule)
|
||
|
||
### `injectType`
|
||
|
||
Type:
|
||
|
||
```ts
|
||
type injectType =
|
||
| "styleTag"
|
||
| "singletonStyleTag"
|
||
| "autoStyleTag"
|
||
| "lazyStyleTag"
|
||
| "lazySingletonStyleTag"
|
||
| "lazyAutoStyleTag"
|
||
| "linkTag";
|
||
```
|
||
|
||
Default: `styleTag`
|
||
|
||
Allows to setup how styles will be injected into the DOM.
|
||
|
||
Possible values:
|
||
|
||
#### `styleTag`
|
||
|
||
Automatically injects styles into the DOM using multiple `<style></style>`. It is **default** behaviour.
|
||
|
||
**component.js**
|
||
|
||
```js
|
||
import "./styles.css";
|
||
```
|
||
|
||
Example with Locals (CSS Modules):
|
||
|
||
**component-with-css-modules.js**
|
||
|
||
```js
|
||
import styles from "./styles.css";
|
||
|
||
const divElement = document.createElement("div");
|
||
divElement.className = styles["my-class"];
|
||
```
|
||
|
||
All locals (class names) stored in imported object.
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
// The `injectType` option can be avoided because it is default behaviour
|
||
{ loader: "style-loader", options: { injectType: "styleTag" } },
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
The loader inject styles like:
|
||
|
||
```html
|
||
<style>
|
||
.foo {
|
||
color: red;
|
||
}
|
||
</style>
|
||
<style>
|
||
.bar {
|
||
color: blue;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
#### `singletonStyleTag`
|
||
|
||
Automatically injects styles into the DOM using one `<style></style>`.
|
||
|
||
> **Warning**
|
||
>
|
||
> Source maps do not work.
|
||
|
||
**component.js**
|
||
|
||
```js
|
||
import "./styles.css";
|
||
```
|
||
|
||
**component-with-css-modules.js**
|
||
|
||
```js
|
||
import styles from "./styles.css";
|
||
|
||
const divElement = document.createElement("div");
|
||
divElement.className = styles["my-class"];
|
||
```
|
||
|
||
All locals (class names) stored in imported object.
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: { injectType: "singletonStyleTag" },
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
The loader inject styles like:
|
||
|
||
```html
|
||
<style>
|
||
.foo {
|
||
color: red;
|
||
}
|
||
.bar {
|
||
color: blue;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
#### `autoStyleTag`
|
||
|
||
Works the same as a [`styleTag`](#styleTag), but if the code is executed in IE6-9, turns on the [`singletonStyleTag`](#singletonStyleTag) mode.
|
||
|
||
#### `lazyStyleTag`
|
||
|
||
Injects styles into the DOM using multiple `<style></style>` on demand.
|
||
We recommend following `.lazy.css` naming convention for lazy styles and the `.css` for basic `style-loader` usage (similar to other file types, i.e. `.lazy.less` and `.less`).
|
||
When you `lazyStyleTag` value the `style-loader` injects the styles lazily making them useable on-demand via `style.use()` / `style.unuse()`.
|
||
|
||
> ⚠️ Behavior is undefined when `unuse` is called more often than `use`. Don't do that.
|
||
|
||
**component.js**
|
||
|
||
```js
|
||
import styles from "./styles.lazy.css";
|
||
|
||
styles.use();
|
||
// For removing styles you can use
|
||
// styles.unuse();
|
||
```
|
||
|
||
**component-with-css-modules.js**
|
||
|
||
```js
|
||
import styles from "./styles.lazy.css";
|
||
|
||
styles.use();
|
||
|
||
const divElement = document.createElement("div");
|
||
divElement.className = styles.locals["my-class"];
|
||
```
|
||
|
||
All locals (class names) stored in `locals` property of imported object.
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
exclude: /\.lazy\.css$/i,
|
||
use: ["style-loader", "css-loader"],
|
||
},
|
||
{
|
||
test: /\.lazy\.css$/i,
|
||
use: [
|
||
{ loader: "style-loader", options: { injectType: "lazyStyleTag" } },
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
The loader inject styles like:
|
||
|
||
```html
|
||
<style>
|
||
.foo {
|
||
color: red;
|
||
}
|
||
</style>
|
||
<style>
|
||
.bar {
|
||
color: blue;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
#### `lazySingletonStyleTag`
|
||
|
||
Injects styles into the DOM using one `<style></style>` on demand.
|
||
We recommend following `.lazy.css` naming convention for lazy styles and the `.css` for basic `style-loader` usage (similar to other file types, i.e. `.lazy.less` and `.less`).
|
||
When you `lazySingletonStyleTag` value the `style-loader` injects the styles lazily making them useable on-demand via `style.use()` / `style.unuse()`.
|
||
|
||
> ⚠️ Source maps do not work.
|
||
|
||
> ⚠️ Behavior is undefined when `unuse` is called more often than `use`. Don't do that.
|
||
|
||
**component.js**
|
||
|
||
```js
|
||
import styles from "./styles.css";
|
||
|
||
styles.use();
|
||
// For removing styles you can use
|
||
// styles.unuse();
|
||
```
|
||
|
||
**component-with-css-modules.js**
|
||
|
||
```js
|
||
import styles from "./styles.lazy.css";
|
||
|
||
styles.use();
|
||
|
||
const divElement = document.createElement("div");
|
||
divElement.className = styles.locals["my-class"];
|
||
```
|
||
|
||
All locals (class names) stored in `locals` property of imported object.
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
exclude: /\.lazy\.css$/i,
|
||
use: ["style-loader", "css-loader"],
|
||
},
|
||
{
|
||
test: /\.lazy\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: { injectType: "lazySingletonStyleTag" },
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
The loader generate this:
|
||
|
||
```html
|
||
<style>
|
||
.foo {
|
||
color: red;
|
||
}
|
||
.bar {
|
||
color: blue;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
#### `lazyAutoStyleTag`
|
||
|
||
Works the same as a [`lazyStyleTag`](#lazyStyleTag), but if the code is executed in IE6-9, turns on the [`lazySingletonStyleTag`](#lazySingletonStyleTag) mode.
|
||
|
||
#### `linkTag`
|
||
|
||
Injects styles into the DOM using multiple `<link rel="stylesheet" href="path/to/file.css">` .
|
||
|
||
> ℹ️ The loader will dynamically insert the `<link href="path/to/file.css" rel="stylesheet">` tag at runtime via JavaScript. You should use [MiniCssExtractPlugin](https://webpack.js.org/plugins/mini-css-extract-plugin/) if you want to include a static `<link href="path/to/file.css" rel="stylesheet">`.
|
||
|
||
```js
|
||
import "./styles.css";
|
||
import "./other-styles.css";
|
||
```
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.link\.css$/i,
|
||
use: [
|
||
{ loader: "style-loader", options: { injectType: "linkTag" } },
|
||
{ loader: "file-loader" },
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
The loader generate this:
|
||
|
||
```html
|
||
<link rel="stylesheet" href="path/to/style.css" />
|
||
<link rel="stylesheet" href="path/to/other-styles.css" />
|
||
```
|
||
|
||
### `attributes`
|
||
|
||
Type:
|
||
|
||
```ts
|
||
type attributes = HTMLAttributes;
|
||
```
|
||
|
||
Default: `{}`
|
||
|
||
If defined, the `style-loader` will attach given attributes with their values on `<style>` / `<link>` element.
|
||
|
||
**component.js**
|
||
|
||
```js
|
||
import style from "./file.css";
|
||
```
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{ loader: "style-loader", options: { attributes: { id: "id" } } },
|
||
{ loader: "css-loader" },
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
```html
|
||
<style id="id"></style>
|
||
```
|
||
|
||
### `insert`
|
||
|
||
Type:
|
||
|
||
```ts
|
||
type insert =
|
||
| string
|
||
| ((htmlElement: HTMLElement, options: Record<string, any>) => void);
|
||
```
|
||
|
||
Default: `head`
|
||
|
||
By default, the `style-loader` appends `<style>`/`<link>` elements to the end of the style target, which is the `<head>` tag of the page unless specified by `insert`.
|
||
This will cause CSS created by the loader to take priority over CSS already present in the target.
|
||
You can use other values if the standard behavior is not suitable for you, but we do not recommend doing this.
|
||
If you target an [iframe](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement) make sure you have sufficient access rights, the styles will be injected into the content document head.
|
||
|
||
#### `string`
|
||
|
||
##### `Selector`
|
||
|
||
Allows to setup custom [query selector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector) where styles inject into the DOM.
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: {
|
||
insert: "body",
|
||
},
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
##### `Absolute path to function`
|
||
|
||
Allows to setup absolute path to custom function that allows to override default behavior and insert styles at any position.
|
||
|
||
> **Warning**
|
||
>
|
||
> Do not forget that this code will be used in the browser and not all browsers support latest ECMA features like `let`, `const`, `arrow function expression` and etc. We recommend using [`babel-loader`](https://webpack.js.org/loaders/babel-loader/) for support latest ECMA features.
|
||
|
||
> **Warning**
|
||
>
|
||
> Do not forget that some DOM methods may not be available in older browsers, we recommended use only [DOM core level 2 properties](https://caniuse.com/#search=DOM%20Core), but it is depends what browsers you want to support
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: {
|
||
insert: require.resolve("modulePath"),
|
||
},
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
A new `<style>`/`<link>` elements will be inserted into at bottom of `body` tag.
|
||
|
||
#### `function`
|
||
|
||
Allows to override default behavior and insert styles at any position.
|
||
|
||
> **Warning**
|
||
>
|
||
> Do not forget that this code will be used in the browser and not all browsers support latest ECMA features like `let`, `const`, `arrow function expression` and etc, we recommend use only ECMA 5 features, but it is depends what browsers you want to support
|
||
|
||
> **Warning**
|
||
>
|
||
> Do not forget that some DOM methods may not be available in older browsers, we recommended use only [DOM core level 2 properties](https://caniuse.com/#search=DOM%20Core), but it is depends what browsers you want to support
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: {
|
||
insert: function insertAtTop(element) {
|
||
var parent = document.querySelector("head");
|
||
// eslint-disable-next-line no-underscore-dangle
|
||
var lastInsertedElement =
|
||
window._lastElementInsertedByStyleLoader;
|
||
|
||
if (!lastInsertedElement) {
|
||
parent.insertBefore(element, parent.firstChild);
|
||
} else if (lastInsertedElement.nextSibling) {
|
||
parent.insertBefore(element, lastInsertedElement.nextSibling);
|
||
} else {
|
||
parent.appendChild(element);
|
||
}
|
||
|
||
// eslint-disable-next-line no-underscore-dangle
|
||
window._lastElementInsertedByStyleLoader = element;
|
||
},
|
||
},
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
Insert styles at top of `head` tag.
|
||
|
||
You can pass any parameters to `style.use(options)` and this value will be passed to `insert` and `styleTagTransform` functions.
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: {
|
||
injectType: "lazyStyleTag",
|
||
// Do not forget that this code will be used in the browser and
|
||
// not all browsers support latest ECMA features like `let`, `const`, `arrow function expression` and etc,
|
||
// we recommend use only ECMA 5 features,
|
||
// but it is depends what browsers you want to support
|
||
insert: function insertIntoTarget(element, options) {
|
||
var parent = options.target || document.head;
|
||
|
||
parent.appendChild(element);
|
||
},
|
||
},
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
Insert styles to the provided element or to the `head` tag if target isn't provided. Now you can inject styles into Shadow DOM (or any other element).
|
||
|
||
**custom-square.css**
|
||
|
||
```css
|
||
div {
|
||
width: 50px;
|
||
height: 50px;
|
||
background-color: red;
|
||
}
|
||
```
|
||
|
||
**custom-square.js**
|
||
|
||
```js
|
||
import customSquareStyles from "./custom-square.css";
|
||
|
||
class CustomSquare extends HTMLElement {
|
||
constructor() {
|
||
super();
|
||
|
||
this.attachShadow({ mode: "open" });
|
||
|
||
const divElement = document.createElement("div");
|
||
|
||
divElement.textContent = "Text content.";
|
||
|
||
this.shadowRoot.appendChild(divElement);
|
||
|
||
customSquareStyles.use({ target: this.shadowRoot });
|
||
|
||
// You can override injected styles
|
||
const bgPurple = new CSSStyleSheet();
|
||
const width = this.getAttribute("w");
|
||
const height = this.getAttribute("h");
|
||
|
||
bgPurple.replace(`div { width: ${width}px; height: ${height}px; }`);
|
||
|
||
this.shadowRoot.adoptedStyleSheets = [bgPurple];
|
||
|
||
// `divElement` will have `100px` width, `100px` height and `red` background color
|
||
}
|
||
}
|
||
|
||
customElements.define("custom-square", CustomSquare);
|
||
|
||
export default CustomSquare;
|
||
```
|
||
|
||
### `styleTagTransform`
|
||
|
||
Type:
|
||
|
||
```ts
|
||
type styleTagTransform =
|
||
| string
|
||
| ((
|
||
css: string,
|
||
styleElement: HTMLStyleElement,
|
||
options: Record<string, any>
|
||
) => void);
|
||
```
|
||
|
||
Default: `undefined`
|
||
|
||
#### `string`
|
||
|
||
Allows to setup absolute path to custom function that allows to override default behavior styleTagTransform.
|
||
|
||
> **Warning**
|
||
>
|
||
> Do not forget that this code will be used in the browser and not all browsers support latest ECMA features like `let`, `const`, `arrow function expression` and etc, we recommend use only ECMA 5 features, but it is depends what browsers you want to support
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: {
|
||
injectType: "styleTag",
|
||
styleTagTransform: require.resolve("module-path"),
|
||
},
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
#### `function`
|
||
|
||
Transform tag and css when insert 'style' tag into the DOM.
|
||
|
||
> **Warning**
|
||
>
|
||
> Do not forget that this code will be used in the browser and not all browsers support latest ECMA features like `let`, `const`, `arrow function expression` and etc, we recommend use only ECMA 5 features, but it is depends what browsers you want to support
|
||
|
||
> **Warning**
|
||
>
|
||
> Do not forget that some DOM methods may not be available in older browsers, we recommended use only [DOM core level 2 properties](https://caniuse.com/#search=DOM%20Core), but it is depends what browsers you want to support
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: {
|
||
injectType: "styleTag",
|
||
styleTagTransform: function (css, style) {
|
||
// Do something ...
|
||
style.innerHTML = `${css}.modify{}\n`;
|
||
|
||
document.head.appendChild(style);
|
||
},
|
||
},
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
### `base`
|
||
|
||
```ts
|
||
type base = number;
|
||
```
|
||
|
||
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.me.uk/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.:
|
||
|
||
**webpack.dll1.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: ["style-loader", "css-loader"],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
**webpack.dll2.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{ loader: "style-loader", options: { base: 1000 } },
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
**webpack.app.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{ loader: "style-loader", options: { base: 2000 } },
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
### `esModule`
|
||
|
||
Type:
|
||
|
||
```ts
|
||
type esModule = boolean;
|
||
```
|
||
|
||
Default: `true`
|
||
|
||
By default, `style-loader` generates JS modules that use the ES modules syntax.
|
||
There are some cases in which using ES modules is beneficial, like in the case of [module concatenation](https://webpack.js.org/plugins/module-concatenation-plugin/) and [tree shaking](https://webpack.js.org/guides/tree-shaking/).
|
||
|
||
You can enable a CommonJS modules syntax using:
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
loader: "style-loader",
|
||
options: {
|
||
esModule: false,
|
||
},
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
## Examples
|
||
|
||
### Recommend
|
||
|
||
For `production` builds it's recommended to extract the CSS from your bundle being able to use parallel loading of CSS/JS resources later on.
|
||
This can be achieved by using the [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin), because it creates separate css files.
|
||
For `development` mode (including `webpack-dev-server`) you can use `style-loader`, because it injects CSS into the DOM using multiple `<style></style>` and works faster.
|
||
|
||
> **Warning**
|
||
>
|
||
> Do not use together `style-loader` and `mini-css-extract-plugin`.
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
|
||
const devMode = process.env.NODE_ENV !== "production";
|
||
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.(sa|sc|c)ss$/,
|
||
use: [
|
||
devMode ? "style-loader" : MiniCssExtractPlugin.loader,
|
||
"css-loader",
|
||
"postcss-loader",
|
||
"sass-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
plugins: [].concat(devMode ? [] : [new MiniCssExtractPlugin()]),
|
||
};
|
||
```
|
||
|
||
### Named export for CSS Modules
|
||
|
||
> **Warning**
|
||
>
|
||
> Names of locals are converted to `camelCase`.
|
||
|
||
> **Warning**
|
||
>
|
||
> It is not allowed to use JavaScript reserved words in css class names.
|
||
|
||
> **Warning**
|
||
>
|
||
> Options `esModule` and `modules.namedExport` in `css-loader` should be enabled.
|
||
|
||
**styles.css**
|
||
|
||
```css
|
||
.foo-baz {
|
||
color: red;
|
||
}
|
||
.bar {
|
||
color: blue;
|
||
}
|
||
```
|
||
|
||
**index.js**
|
||
|
||
```js
|
||
import { fooBaz, bar } from "./styles.css";
|
||
|
||
console.log(fooBaz, bar);
|
||
```
|
||
|
||
You can enable a ES module named export using:
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
},
|
||
{
|
||
loader: "css-loader",
|
||
options: {
|
||
modules: {
|
||
namedExport: true,
|
||
},
|
||
},
|
||
},
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
### Source maps
|
||
|
||
The loader automatically inject source maps when previous loader emit them.
|
||
Therefore, to generate source maps, set the `sourceMap` option to `true` for the previous loader.
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
"style-loader",
|
||
{ loader: "css-loader", options: { sourceMap: true } },
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
### Nonce
|
||
|
||
If you are using a [Content Security Policy](https://www.w3.org/TR/CSP3/) (CSP), the injected code will usually be blocked. A workaround is to use a nonce. Note, however, that using a nonce significantly reduces the protection provided by the CSP. You can read more about the security impact in [the specification](https://www.w3.org/TR/CSP3/#security-considerations). The better solution is not to use this loader in production.
|
||
|
||
There are two ways to work with `nonce`:
|
||
|
||
- using the `attributes` option
|
||
- using the `__webpack_nonce__` variable
|
||
|
||
> **Warning**
|
||
>
|
||
> the `attributes` option takes precedence over the `__webpack_nonce__` variable
|
||
|
||
#### `attributes`
|
||
|
||
**component.js**
|
||
|
||
```js
|
||
import "./style.css";
|
||
```
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: {
|
||
attributes: {
|
||
nonce: "12345678",
|
||
},
|
||
},
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
The loader generate:
|
||
|
||
```html
|
||
<style nonce="12345678">
|
||
.foo {
|
||
color: red;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
#### `__webpack_nonce__`
|
||
|
||
**create-nonce.js**
|
||
|
||
```js
|
||
__webpack_nonce__ = "12345678";
|
||
```
|
||
|
||
**component.js**
|
||
|
||
```js
|
||
import "./create-nonce.js";
|
||
import "./style.css";
|
||
```
|
||
|
||
Alternative example for `require`:
|
||
|
||
**component.js**
|
||
|
||
```js
|
||
__webpack_nonce__ = "12345678";
|
||
|
||
require("./style.css");
|
||
```
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: ["style-loader", "css-loader"],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
The loader generate:
|
||
|
||
```html
|
||
<style nonce="12345678">
|
||
.foo {
|
||
color: red;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
#### Insert styles at top
|
||
|
||
Inserts styles at top of `head` tag.
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: {
|
||
insert: function insertAtTop(element) {
|
||
var parent = document.querySelector("head");
|
||
var lastInsertedElement =
|
||
window._lastElementInsertedByStyleLoader;
|
||
|
||
if (!lastInsertedElement) {
|
||
parent.insertBefore(element, parent.firstChild);
|
||
} else if (lastInsertedElement.nextSibling) {
|
||
parent.insertBefore(element, lastInsertedElement.nextSibling);
|
||
} else {
|
||
parent.appendChild(element);
|
||
}
|
||
|
||
window._lastElementInsertedByStyleLoader = element;
|
||
},
|
||
},
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
#### Insert styles before target element
|
||
|
||
Inserts styles before `#id` element.
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: {
|
||
insert: function insertBeforeAt(element) {
|
||
const parent = document.querySelector("head");
|
||
const target = document.querySelector("#id");
|
||
|
||
const lastInsertedElement =
|
||
window._lastElementInsertedByStyleLoader;
|
||
|
||
if (!lastInsertedElement) {
|
||
parent.insertBefore(element, target);
|
||
} else if (lastInsertedElement.nextSibling) {
|
||
parent.insertBefore(element, lastInsertedElement.nextSibling);
|
||
} else {
|
||
parent.appendChild(element);
|
||
}
|
||
|
||
window._lastElementInsertedByStyleLoader = element;
|
||
},
|
||
},
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
#### Custom Elements (Shadow DOM)
|
||
|
||
You can define custom target for your styles for the `lazyStyleTag` type.
|
||
|
||
**webpack.config.js**
|
||
|
||
```js
|
||
module.exports = {
|
||
module: {
|
||
rules: [
|
||
{
|
||
test: /\.css$/i,
|
||
use: [
|
||
{
|
||
loader: "style-loader",
|
||
options: {
|
||
injectType: "lazyStyleTag",
|
||
// Do not forget that this code will be used in the browser and
|
||
// not all browsers support latest ECMA features like `let`, `const`, `arrow function expression` and etc,
|
||
// we recommend use only ECMA 5 features,
|
||
// but it is depends what browsers you want to support
|
||
insert: function insertIntoTarget(element, options) {
|
||
var parent = options.target || document.head;
|
||
|
||
parent.appendChild(element);
|
||
},
|
||
},
|
||
},
|
||
"css-loader",
|
||
],
|
||
},
|
||
],
|
||
},
|
||
};
|
||
```
|
||
|
||
Insert styles to the provided element or to the `head` tag if target isn't provided.
|
||
|
||
**custom-square.css**
|
||
|
||
```css
|
||
div {
|
||
width: 50px;
|
||
height: 50px;
|
||
background-color: red;
|
||
}
|
||
```
|
||
|
||
**custom-square.js**
|
||
|
||
```js
|
||
import customSquareStyles from "./custom-square.css";
|
||
|
||
class CustomSquare extends HTMLElement {
|
||
constructor() {
|
||
super();
|
||
|
||
this.attachShadow({ mode: "open" });
|
||
|
||
const divElement = document.createElement("div");
|
||
|
||
divElement.textContent = "Text content.";
|
||
|
||
this.shadowRoot.appendChild(divElement);
|
||
|
||
customSquareStyles.use({ target: this.shadowRoot });
|
||
|
||
// You can override injected styles
|
||
const bgPurple = new CSSStyleSheet();
|
||
const width = this.getAttribute("w");
|
||
const height = this.getAttribute("h");
|
||
|
||
bgPurple.replace(`div { width: ${width}px; height: ${height}px; }`);
|
||
|
||
this.shadowRoot.adoptedStyleSheets = [bgPurple];
|
||
|
||
// `divElement` will have `100px` width, `100px` height and `red` background color
|
||
}
|
||
}
|
||
|
||
customElements.define("custom-square", CustomSquare);
|
||
|
||
export default CustomSquare;
|
||
```
|
||
|
||
## Contributing
|
||
|
||
Please take a moment to read our contributing guidelines if you haven't yet done so.
|
||
|
||
[CONTRIBUTING](./.github/CONTRIBUTING.md)
|
||
|
||
## License
|
||
|
||
[MIT](./LICENSE)
|
||
|
||
[npm]: https://img.shields.io/npm/v/style-loader.svg
|
||
[npm-url]: https://npmjs.com/package/style-loader
|
||
[node]: https://img.shields.io/node/v/style-loader.svg
|
||
[node-url]: https://nodejs.org
|
||
[tests]: https://github.com/webpack-contrib/style-loader/workflows/style-loader/badge.svg
|
||
[tests-url]: https://github.com/webpack-contrib/style-loader/actions
|
||
[cover]: https://codecov.io/gh/webpack-contrib/style-loader/branch/master/graph/badge.svg
|
||
[cover-url]: https://codecov.io/gh/webpack-contrib/style-loader
|
||
[discussion]: https://img.shields.io/github/discussions/webpack/webpack
|
||
[discussion-url]: https://github.com/webpack/webpack/discussions
|
||
[size]: https://packagephobia.now.sh/badge?p=style-loader
|
||
[size-url]: https://packagephobia.now.sh/result?p=style-loader
|