UNPKG

8.96 kBMarkdownView Raw
1# rollup-plugin-styles
2
3[![npm version](https://img.shields.io/npm/v/rollup-plugin-styles)](https://www.npmjs.com/package/rollup-plugin-styles)
4[![monthly downloads count](https://img.shields.io/npm/dm/rollup-plugin-styles)](https://www.npmjs.com/package/rollup-plugin-styles)
5[![required rollup version](https://img.shields.io/npm/dependency-version/rollup-plugin-styles/peer/rollup)](https://www.npmjs.com/package/rollup)
6[![dependencies status](https://img.shields.io/david/Anidetrix/rollup-plugin-styles)](https://david-dm.org/Anidetrix/rollup-plugin-styles)
7[![build status](https://github.com/Anidetrix/rollup-plugin-styles/workflows/CI/badge.svg)](https://github.com/Anidetrix/rollup-plugin-styles/actions?query=workflow%3ACI)
8[![code coverage](https://codecov.io/gh/Anidetrix/rollup-plugin-styles/branch/master/graph/badge.svg)](https://codecov.io/gh/Anidetrix/rollup-plugin-styles)
9[![license](https://img.shields.io/github/license/Anidetrix/rollup-plugin-styles)](./LICENSE)
10
11### 🎨 Universal [Rollup](https://github.com/rollup/rollup) plugin for styles:
12
13- [PostCSS](https://github.com/postcss/postcss)
14- [Sass](https://github.com/sass/dart-sass)
15- [Less](https://github.com/less/less.js)
16- [Stylus](https://github.com/stylus/stylus)
17- [CSS Modules](https://github.com/css-modules/css-modules)
18- URL resolving/rewriting with asset handling
19- Ability to use `@import` statements inside regular CSS
20
21...and more!
22
23## Table of Contents
24
25- [Installation](#installation)
26- [Usage](#usage)
27 - [Importing a file](#importing-a-file)
28 - [CSS/Stylus](#cssstylus)
29 - [Sass/Less](#sassless)
30 - [CSS Injection](#css-injection)
31 - [CSS Extraction](#css-extraction)
32 - [Emitting processed CSS](#emitting-processed-css)
33 - [CSS Modules](#css-modules)
34 - [With Sass/Less/Stylus](#with-sasslessstylus)
35 - [`fibers` (**Sass only**)](#fibers-sass-only)
36- [Configuration](#configuration)
37- [Main differences from `rollup-plugin-postcss`](#main-differences-from-rollup-plugin-postcss)
38- [Contributing](#contributing)
39- [License](#license)
40- [Thanks](#thanks)
41
42## Installation
43
44```bash
45npm install -D rollup-plugin-styles # npm
46
47pnpm add -D rollup-plugin-styles # pnpm
48
49yarn add rollup-plugin-styles --dev # yarn 1.x
50```
51
52## Usage
53
54```js
55// rollup.config.js
56import styles from "rollup-plugin-styles";
57
58export default {
59 output: {
60 // Governs names of CSS files (for assets from CSS use `hash` option for url handler).
61 // Note: using value below will put `.css` files near js,
62 // but make sure to adjust `hash`, `assetDir` and `publicPath`
63 // options for url handler accordingly.
64 assetFileNames: "[name]-[hash][extname]",
65 },
66 plugins: [styles()],
67};
68```
69
70After that you can import CSS files in your code:
71
72```js
73import "./style.css";
74```
75
76Default mode is `inject`, which means CSS is embedded inside JS and injected into `<head>` at runtime, with ability to pass options to CSS injector or even pass your own injector.
77
78CSS is available as default export in `inject` and `extract` modes, but if [CSS Modules](https://github.com/css-modules/css-modules) are enabled you need to use named `css` export.
79
80```js
81// Injects CSS, also available as `style` in this example
82import style from "./style.css";
83// Named export of CSS string
84import { css } from "./style.css";
85```
86
87In `emit` mode none of the exports are available as CSS is purely processed and passed along the build pipeline, which is useful if you want to preprocess CSS before using it with CSS consuming plugins, e.g. [rollup-plugin-lit-css](https://github.com/bennypowers/rollup-plugin-lit-css).
88
89PostCSS configuration files will be found and loaded automatically, but this behavior is configurable using `config` option.
90
91### Importing a file
92
93#### CSS/Stylus
94
95```css
96/* Import from `node_modules` */
97@import "bulma/css/bulma";
98/* Local import */
99@import "./custom";
100/* ...or (if no package named `custom` in `node_modules`) */
101@import "custom";
102```
103
104#### Sass/Less
105
106You can prepend the path with `~` to resolve in `node_modules`:
107
108```scss
109// Import from `node_modules`
110@import "~bulma/css/bulma";
111// Local import
112@import "custom";
113// ...or
114@import "./custom";
115```
116
117Also note that partials are considered first, e.g.
118
119```scss
120@import "custom";
121```
122
123Will look for `_custom` first (_with the approptiate extension(s)_), and then for `custom` if `_custom` doesn't exist.
124
125### CSS Injection
126
127```js
128styles({
129 mode: "inject", // Unnecessary, set by default
130 // ...or with custom options for injector
131 mode: ["inject", { container: "body", singleTag: true, prepend: true }],
132 // ...or with custom injector
133 mode: ["inject", yourInjectorFn],
134});
135```
136
137### CSS Extraction
138
139```js
140styles({
141 mode: "extract",
142 // ... or with relative to output dir/output file's basedir (but not outside of it)
143 mode: ["extract", "awesome-bundle.css"],
144});
145```
146
147### Emitting processed CSS
148
149```js
150// rollup.config.js
151import styles from "rollup-plugin-styles";
152
153// Any plugin which consumes pure CSS
154import litcss from "rollup-plugin-lit-css";
155
156export default {
157 plugins: [
158 styles({ mode: "emit" }),
159
160 // Make sure to list it after this one
161 litcss(),
162 ],
163};
164```
165
166### [CSS Modules](https://github.com/css-modules/css-modules)
167
168```js
169styles({
170 modules: true,
171 // ...or with custom options
172 modules: {},
173 // ...additionally using autoModules
174 autoModules: true,
175 // ...with custom regex
176 autoModules: /\.mod\.\S+$/,
177 // ...or custom function
178 autoModules: id => id.includes(".modular."),
179});
180```
181
182### With Sass/Less/Stylus
183
184Install corresponding dependency:
185
186- For `Sass` support install `node-sass` or `sass`:
187
188 ```bash
189 npm install -D node-sass # npm
190
191 pnpm add -D node-sass # pnpm
192
193 yarn add node-sass --dev # yarn 1.x
194 ```
195
196 ```bash
197 npm install -D sass # npm
198
199 pnpm add -D sass # pnpm
200
201 yarn add sass --dev # yarn 1.x
202 ```
203
204- For `Less` support install `less`:
205
206 ```bash
207 npm install -D less # npm
208
209 pnpm add -D less # pnpm
210
211 yarn add less --dev # yarn 1.x
212 ```
213
214- For `Stylus` support install `stylus`:
215
216 ```bash
217 npm install -D stylus # npm
218
219 pnpm add -D stylus # pnpm
220
221 yarn add stylus --dev # yarn 1.x
222 ```
223
224That's it, now you can import `.scss` `.sass` `.less` `.styl` `.stylus` files in your code.
225
226### `fibers` (**Sass only**)
227
228By default, `fibers` package will be loaded automatically if available when using `sass` implementation.
229
230> When installed via npm, `Dart Sass` supports a JavaScript API that's fully compatible with `Node Sass` <...>, with support for both the render() and renderSync() functions. <...>
231>
232> Note however that by default, **renderSync() is more than twice as fast as render()** due to the overhead of asynchronous callbacks. To avoid this performance hit, render() can use the `fibers` package to call asynchronous importers from the synchronous code path.
233>
234> [Source](https://github.com/sass/dart-sass/blob/master/README.md#javascript-api)
235
236To install `fibers`:
237
238```bash
239npm install -D fibers # npm
240
241pnpm add -D fibers # pnpm
242
243yarn add fibers --dev # yarn 1.x
244```
245
246## Configuration
247
248See [API Reference for `Options`](https://anidetrix.github.io/rollup-plugin-styles/interfaces/_index_d_.options.html) for full list of available options.
249
250## Main differences from [rollup-plugin-postcss](https://github.com/egoist/rollup-plugin-postcss)
251
252- Written completely in TypeScript
253- Up-to-date [CSS Modules](https://github.com/css-modules/css-modules) implementation
254- Built-in `@import` handler
255- Built-in assets handler
256- Respects `output.assetFileNames`
257- Code splitting support
258- Multi entry support
259- Ability to emit pure CSS for other plugins
260- Correct multiple instance support with check for already processed files
261- Support for implementation and `fibers` forcing for Sass
262- Support for partials and `~` in Less import statements
263- Sourcemaps include source content
264- Proper sourcemap generation for all loaders
265- Correct inline sourcemaps
266- Correct relative source paths in extracted sourcemaps
267- Extracts sourcemaps from loaded files
268- More smaller things that I forgot
269
270## Contributing
271
272Any contributions are always welcome, not only Pull Requests! 😀
273
274- **QA**: file bug reports, the more details you can give the better
275- **Code**: take a look at the [open issues](https://github.com/Anidetrix/rollup-plugin-styles/issues), even if you can't write code showing that you care about a given issue matters
276- **Ideas**: feature requests are welcome, even ambitious ones
277- **Donations**: financial support helps to dedicate more time to this project
278
279Your First Contribution? You can learn how from this _free_ series, [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github).
280
281## License
282
283MIT &copy; [Anton Kudryavtsev](https://github.com/Anidetrix)
284
285## Thanks
286
287- [rollup-plugin-postcss](https://github.com/egoist/rollup-plugin-postcss) - for good reference 👍
288- [rollup](https://github.com/rollup/rollup) - for awesome bundler 😎