1 | # rollup-plugin-postcss
|
2 |
|
3 | [![NPM version](https://img.shields.io/npm/v/rollup-plugin-postcss.svg?style=flat)](https://npmjs.com/package/rollup-plugin-postcss) [![NPM downloads](https://img.shields.io/npm/dm/rollup-plugin-postcss.svg?style=flat)](https://npmjs.com/package/rollup-plugin-postcss) [![Build Status](https://img.shields.io/circleci/project/egoist/rollup-plugin-postcss/master.svg?style=flat)](https://circleci.com/gh/egoist/rollup-plugin-postcss) [![codecov](https://codecov.io/gh/egoist/rollup-plugin-postcss/branch/master/graph/badge.svg)](https://codecov.io/gh/egoist/rollup-plugin-postcss)
|
4 | [![donate](https://img.shields.io/badge/$-donate-ff69b4.svg?maxAge=2592000&style=flat)](https://github.com/egoist/donate)
|
5 |
|
6 | <img align="right" width="95" height="95"
|
7 | title="Philosopher’s stone, logo of PostCSS"
|
8 | src="http://postcss.github.io/postcss/logo.svg">
|
9 |
|
10 | Seamless integration between [Rollup](https://github.com/rollup/rollup) and [PostCSS](https://github.com/postcss/postcss).
|
11 |
|
12 | ## Install
|
13 |
|
14 | ```bash
|
15 | yarn add rollup-plugin-postcss --dev
|
16 | ```
|
17 |
|
18 | ## Usage
|
19 |
|
20 | You are viewing the docs for `v1.0`, for `v0.5` please see [here](https://github.com/egoist/rollup-plugin-postcss/tree/0.5).
|
21 |
|
22 | ```js
|
23 | // rollup.config.js
|
24 | import postcss from 'rollup-plugin-postcss'
|
25 |
|
26 | export default {
|
27 | plugins: [
|
28 | postcss({
|
29 | plugins: []
|
30 | })
|
31 | ]
|
32 | }
|
33 | ```
|
34 |
|
35 | Then you can use CSS files:
|
36 |
|
37 | ```js
|
38 | import './style.css'
|
39 | ```
|
40 |
|
41 | Note that the generated CSS will be injected to `<head>` by default, and the CSS string is also available as default export unless `extract: true`:
|
42 |
|
43 | ```js
|
44 | // Inject to `<head>` and also available as `style`
|
45 | import style from './style.css'
|
46 | ```
|
47 |
|
48 | It will also automatically use local PostCSS config files.
|
49 |
|
50 | ### Extract CSS
|
51 |
|
52 | ```js
|
53 | postcss({
|
54 | extract: true
|
55 | })
|
56 | ```
|
57 |
|
58 | ### CSS modules
|
59 |
|
60 | ```js
|
61 | postcss({
|
62 | modules: true,
|
63 | // Or with custom options for `postcss-modules`
|
64 | modules: {}
|
65 | })
|
66 | ```
|
67 |
|
68 | ### With Sass/Stylus/Less
|
69 |
|
70 | Install corresponding dependency:
|
71 |
|
72 | - For `Sass` install `node-sass`: `yarn add node-sass --dev`
|
73 | - For `Stylus` Install `stylus`: `yarn add stylus --dev`
|
74 | - For `Less` Install `less`: `yarn add less --dev`
|
75 |
|
76 | That's it, you can now import `.styl` `.scss` `.sass` `.less` files in your library.
|
77 |
|
78 | #### imports
|
79 |
|
80 | __For Sass/Scss Only.__
|
81 |
|
82 | Similar to how webpack's [sass-loader](https://github.com/webpack-contrib/sass-loader#imports) works, you can prepend the path with `~` to tell this plugin to resolve in `node_modules`:
|
83 |
|
84 | ```sass
|
85 | @import "~bootstrap/dist/css/bootstrap";
|
86 | ```
|
87 |
|
88 | ## Options
|
89 |
|
90 | ### plugins
|
91 |
|
92 | Type: `Array`
|
93 |
|
94 | PostCSS Plugins.
|
95 |
|
96 | ### inject
|
97 |
|
98 | Type: `boolean` `object`<br>
|
99 | Default: `true`
|
100 |
|
101 | Inject CSS into `<head>`, it's always `false` when `extract: true`.
|
102 |
|
103 | You can also use it as options for [`style-inject`](https://github.com/egoist/style-inject#options).
|
104 |
|
105 | ### extract
|
106 |
|
107 | Type: `boolean` `string`<br>
|
108 | Default: `false`
|
109 |
|
110 | Extract CSS to the same location where JS file is generated but with `.css` extension.
|
111 |
|
112 | You can also set it to an absolute path.
|
113 |
|
114 | ### modules
|
115 |
|
116 | Type: `boolean` `object`<br>
|
117 | Default: `false`
|
118 |
|
119 | Enable CSS modules or set options for `postcss-modules`.
|
120 |
|
121 | ### namedExports
|
122 |
|
123 | Type: `boolean` `function`<br>
|
124 | Default: `false`
|
125 |
|
126 | Use named exports alongside default export.
|
127 |
|
128 | You can supply a function to control how exported named is generated:
|
129 |
|
130 | ```js
|
131 | namedExports(name) {
|
132 | // Maybe you simply want to convert dash to underscore
|
133 | return name.replace(/-/g, '_')
|
134 | }
|
135 | ```
|
136 |
|
137 | If you set it to `true`, the following will happen when importing specific classNames:
|
138 |
|
139 | - dashed class names will be transformed by replacing all the dashes to `$` sign wrapped underlines, eg. `--` => `$__$`
|
140 | - js protected names used as your style class names, will be transformed by wrapping the names between `$` signs, eg. `switch` => `$switch$`
|
141 |
|
142 | All transformed names will be logged in your terminal like:
|
143 |
|
144 | ```bash
|
145 | Exported "new" as "$new$" in test/fixtures/named-exports/style.css
|
146 | ```
|
147 |
|
148 | The original will not be removed, it's still available on `default` export:
|
149 |
|
150 | ```js
|
151 | import style, { class$_$name, class$__$name, $switch$ } from './style.css'
|
152 | console.log(style['class-name'] === class$_$name) // true
|
153 | console.log(style['class--name'] === class$__$name) // true
|
154 | console.log(style['switch'] === $switch$) // true
|
155 | ```
|
156 |
|
157 | ### minimize
|
158 |
|
159 | Type: `boolean` `object`<br>
|
160 | Default: `false`
|
161 |
|
162 | Minimize CSS, `boolean` or options for `cssnano`.
|
163 |
|
164 | ### sourceMap
|
165 |
|
166 | Type: `boolean` `"inline"`
|
167 |
|
168 | Enable sourceMap.
|
169 |
|
170 | ### parser
|
171 |
|
172 | Type: `string` `function`
|
173 |
|
174 | PostCSS parser, like `sugarss`.
|
175 |
|
176 | ### stringifier
|
177 |
|
178 | Type: `string` `function`
|
179 |
|
180 | PostCSS Stringifier.
|
181 |
|
182 | ### syntax
|
183 |
|
184 | Type: `string` `function`
|
185 |
|
186 | PostCSS Syntax.
|
187 |
|
188 | ### exec
|
189 |
|
190 | Type: `boolean`
|
191 |
|
192 | Enable PostCSS Parser support in `CSS-in-JS`.
|
193 |
|
194 | ### config
|
195 |
|
196 | Type: `boolean` `object`<br>
|
197 | Default: `true`
|
198 |
|
199 | Load PostCSS config file.
|
200 |
|
201 | #### config.path
|
202 |
|
203 | Type: `string`
|
204 |
|
205 | The path to config file, so that we can skip searching.
|
206 |
|
207 | #### config.ctx
|
208 |
|
209 | Type: `object`
|
210 |
|
211 | [`ctx`](https://github.com/michael-ciniawsky/postcss-load-config#context) argument for PostCSS config file.
|
212 |
|
213 | Note: Every keys you pass to `config.ctx` will be available under `options` inside
|
214 | the postcss config.
|
215 |
|
216 | ```js
|
217 | // rollup.config.js
|
218 | postcss({
|
219 | config: {
|
220 | ctx: {
|
221 | foo: 'bar'
|
222 | }
|
223 | }
|
224 | })
|
225 |
|
226 | // postcss.config.js
|
227 | module.exports = context => {
|
228 | console.log(context.options.foo) // 'bar'
|
229 |
|
230 | return {}
|
231 | }
|
232 | ```
|
233 |
|
234 | ### use
|
235 |
|
236 | Type: `name[]` `[name, options][]`<br>
|
237 | Default: `['sass', 'stylus', 'less']`
|
238 |
|
239 | Use a loader, currently built-in loaders are:
|
240 |
|
241 | - `sass` (Support `.scss` and `.sass`)
|
242 | - `stylus` (Support `.styl` and `.stylus`)
|
243 | - `less` (Support `.less`)
|
244 |
|
245 | They are executed from right to left.
|
246 |
|
247 | ### loaders
|
248 |
|
249 | Type: `Loader[]`
|
250 |
|
251 | An array of custom loaders, check out our [sass-loader](./src/sass-loader.js) as example.
|
252 |
|
253 | ```js
|
254 | interface Loader {
|
255 | name: string,
|
256 | test: RegExp,
|
257 | process: (this: Context, input: Payload) => Promise<Payload> | Payload
|
258 | }
|
259 |
|
260 | interface Context {
|
261 | /** Loader options */
|
262 | options: any
|
263 | /** Sourcemap */
|
264 | sourceMap: any
|
265 | /** Resource path */
|
266 | id: string
|
267 | }
|
268 |
|
269 | interface Payload {
|
270 | /** File content */
|
271 | code: string
|
272 | /** Sourcemap */
|
273 | map?: string | SourceMap
|
274 | }
|
275 | ```
|
276 |
|
277 | ### onImport
|
278 |
|
279 | Type: `id => void`
|
280 |
|
281 | A function to be invoked when an import for CSS file is detected.
|
282 |
|
283 | ## License
|
284 |
|
285 | MIT © [EGOIST](https://github.com/egoist)
|