UNPKG

6.23 kBMarkdownView Raw
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
10Seamless integration between [Rollup](https://github.com/rollup/rollup) and [PostCSS](https://github.com/postcss/postcss).
11
12## Install
13
14```bash
15yarn add rollup-plugin-postcss --dev
16```
17
18## Usage
19
20You 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
24import postcss from 'rollup-plugin-postcss'
25
26export default {
27 plugins: [
28 postcss({
29 plugins: []
30 })
31 ]
32}
33```
34
35Then you can use CSS files:
36
37```js
38import './style.css'
39```
40
41Note 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`
45import style from './style.css'
46```
47
48It will also automatically use local PostCSS config files.
49
50### Extract CSS
51
52```js
53postcss({
54 extract: true
55})
56```
57
58### CSS modules
59
60```js
61postcss({
62 modules: true,
63 // Or with custom options for `postcss-modules`
64 modules: {}
65})
66```
67
68### With Sass/Stylus/Less
69
70Install 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
76That's it, you can now import `.styl` `.scss` `.sass` `.less` files in your library.
77
78#### imports
79
80__For Sass/Scss Only.__
81
82Similar 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
92Type: `Array`
93
94PostCSS Plugins.
95
96### inject
97
98Type: `boolean` `object`<br>
99Default: `true`
100
101Inject CSS into `<head>`, it's always `false` when `extract: true`.
102
103You can also use it as options for [`style-inject`](https://github.com/egoist/style-inject#options).
104
105### extract
106
107Type: `boolean` `string`<br>
108Default: `false`
109
110Extract CSS to the same location where JS file is generated but with `.css` extension.
111
112You can also set it to an absolute path.
113
114### modules
115
116Type: `boolean` `object`<br>
117Default: `false`
118
119Enable CSS modules or set options for `postcss-modules`.
120
121### namedExports
122
123Type: `boolean` `function`<br>
124Default: `false`
125
126Use named exports alongside default export.
127
128You can supply a function to control how exported named is generated:
129
130```js
131namedExports(name) {
132 // Maybe you simply want to convert dash to underscore
133 return name.replace(/-/g, '_')
134}
135```
136
137If 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
142All transformed names will be logged in your terminal like:
143
144```bash
145Exported "new" as "$new$" in test/fixtures/named-exports/style.css
146```
147
148The original will not be removed, it's still available on `default` export:
149
150```js
151import style, { class$_$name, class$__$name, $switch$ } from './style.css'
152console.log(style['class-name'] === class$_$name) // true
153console.log(style['class--name'] === class$__$name) // true
154console.log(style['switch'] === $switch$) // true
155```
156
157### minimize
158
159Type: `boolean` `object`<br>
160Default: `false`
161
162Minimize CSS, `boolean` or options for `cssnano`.
163
164### sourceMap
165
166Type: `boolean` `"inline"`
167
168Enable sourceMap.
169
170### parser
171
172Type: `string` `function`
173
174PostCSS parser, like `sugarss`.
175
176### stringifier
177
178Type: `string` `function`
179
180PostCSS Stringifier.
181
182### syntax
183
184Type: `string` `function`
185
186PostCSS Syntax.
187
188### exec
189
190Type: `boolean`
191
192Enable PostCSS Parser support in `CSS-in-JS`.
193
194### config
195
196Type: `boolean` `object`<br>
197Default: `true`
198
199Load PostCSS config file.
200
201#### config.path
202
203Type: `string`
204
205The path to config file, so that we can skip searching.
206
207#### config.ctx
208
209Type: `object`
210
211[`ctx`](https://github.com/michael-ciniawsky/postcss-load-config#context) argument for PostCSS config file.
212
213Note: Every keys you pass to `config.ctx` will be available under `options` inside
214the postcss config.
215
216```js
217// rollup.config.js
218postcss({
219 config: {
220 ctx: {
221 foo: 'bar'
222 }
223 }
224})
225
226// postcss.config.js
227module.exports = context => {
228 console.log(context.options.foo) // 'bar'
229
230 return {}
231}
232```
233
234### use
235
236Type: `name[]` `[name, options][]`<br>
237Default: `['sass', 'stylus', 'less']`
238
239Use 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
245They are executed from right to left.
246
247### loaders
248
249Type: `Loader[]`
250
251An array of custom loaders, check out our [sass-loader](./src/sass-loader.js) as example.
252
253```js
254interface Loader {
255 name: string,
256 test: RegExp,
257 process: (this: Context, input: Payload) => Promise<Payload> | Payload
258}
259
260interface Context {
261 /** Loader options */
262 options: any
263 /** Sourcemap */
264 sourceMap: any
265 /** Resource path */
266 id: string
267}
268
269interface Payload {
270 /** File content */
271 code: string
272 /** Sourcemap */
273 map?: string | SourceMap
274}
275```
276
277### onImport
278
279Type: `id => void`
280
281A function to be invoked when an import for CSS file is detected.
282
283## License
284
285MIT &copy; [EGOIST](https://github.com/egoist)