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
|
45 | npm install -D rollup-plugin-styles # npm
|
46 |
|
47 | pnpm add -D rollup-plugin-styles # pnpm
|
48 |
|
49 | yarn add rollup-plugin-styles --dev # yarn 1.x
|
50 | ```
|
51 |
|
52 | ## Usage
|
53 |
|
54 | ```js
|
55 | // rollup.config.js
|
56 | import styles from "rollup-plugin-styles";
|
57 |
|
58 | export 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 |
|
70 | After that you can import CSS files in your code:
|
71 |
|
72 | ```js
|
73 | import "./style.css";
|
74 | ```
|
75 |
|
76 | Default 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 |
|
78 | CSS 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
|
82 | import style from "./style.css";
|
83 | // Named export of CSS string
|
84 | import { css } from "./style.css";
|
85 | ```
|
86 |
|
87 | In `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 |
|
89 | PostCSS 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 |
|
106 | You 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 |
|
117 | Also note that partials are considered first, e.g.
|
118 |
|
119 | ```scss
|
120 | @import "custom";
|
121 | ```
|
122 |
|
123 | Will 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
|
128 | styles({
|
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
|
140 | styles({
|
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
|
151 | import styles from "rollup-plugin-styles";
|
152 |
|
153 | // Any plugin which consumes pure CSS
|
154 | import litcss from "rollup-plugin-lit-css";
|
155 |
|
156 | export 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
|
169 | styles({
|
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 |
|
184 | Install 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 |
|
224 | That's it, now you can import `.scss` `.sass` `.less` `.styl` `.stylus` files in your code.
|
225 |
|
226 | ### `fibers` (**Sass only**)
|
227 |
|
228 | By 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 |
|
236 | To install `fibers`:
|
237 |
|
238 | ```bash
|
239 | npm install -D fibers # npm
|
240 |
|
241 | pnpm add -D fibers # pnpm
|
242 |
|
243 | yarn add fibers --dev # yarn 1.x
|
244 | ```
|
245 |
|
246 | ## Configuration
|
247 |
|
248 | See [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 |
|
272 | Any 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 |
|
279 | Your 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 |
|
283 | MIT © [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 😎
|