source: trip-planner-front/node_modules/stylus-loader/README.md@ 6a3a178

Last change on this file since 6a3a178 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 17.9 KB
Line 
1<div align="center">
2 <a href="https://github.com/webpack/webpack">
3 <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg">
4 </a>
5</div>
6
7[![npm][npm]][npm-url]
8[![node][node]][node-url]
9[![deps][deps]][deps-url]
10[![tests][tests]][tests-url]
11[![cover][cover]][cover-url]
12[![chat][chat]][chat-url]
13[![size][size]][size-url]
14
15# stylus-loader
16
17A Stylus loader for webpack. Compiles Styl to CSS.
18
19## Getting Started
20
21To begin, you'll need to install `stylus` and `stylus-loader`:
22
23```console
24$ npm install stylus stylus-loader --save-dev
25```
26
27Then add the loader to your `webpack` config. For example:
28
29**webpack.config.js**
30
31```js
32module.exports = {
33 module: {
34 rules: [
35 {
36 test: /\.styl$/,
37 loader: "stylus-loader", // compiles Styl to CSS
38 },
39 ],
40 },
41};
42```
43
44And run `webpack` via your preferred method.
45
46## Options
47
48| Name | Type | Default | Description |
49| :---------------------------------------: | :------------------: | :----------------: | :------------------------------------------------------- |
50| **[`stylusOptions`](#stylusOptions)** | `{Object\|Function}` | `{}` | Options for Stylus. |
51| **[`sourceMap`](#sourcemap)** | `{Boolean}` | `compiler.devtool` | Enables/Disables generation of source maps. |
52| **[`webpackImporter`](#webpackimporter)** | `{Boolean}` | `true` | Enables/Disables the default Webpack importer. |
53| **[`additionalData`](#additionalData)** | `{String\|Function}` | `undefined` | Prepends/Appends `Stylus` code to the actual entry file. |
54| **[`implementation`](#implementation)** | `{String\|Function}` | `stylus` | Setup Stylus implementation to use. |
55
56### `stylusOptions`
57
58Type: `Object|Function`
59Default: `{}`
60
61You can pass any Stylus specific options to the `stylus-loader` through the `stylusOptions` property in the [loader options](https://webpack.js.org/configuration/module/#rule-options-rule-query).
62See the [Stylus documentation](https://stylus-lang.com/docs/js.html).
63Options in dash-case should use camelCase.
64
65#### `Object`
66
67Use an object to pass options through to Stylus.
68
69**webpack.config.js**
70
71```js
72module.exports = {
73 module: {
74 rules: [
75 {
76 test: /\.styl$/,
77 use: [
78 {
79 loader: "style-loader",
80 },
81 {
82 loader: "css-loader",
83 },
84 {
85 loader: "stylus-loader",
86 options: {
87 stylusOptions: {
88 /**
89 * Specify Stylus plugins to use. Plugins may be passed as
90 * strings instead of importing them in your Webpack config.
91 *
92 * @type {(string|Function)[]}
93 * @default []
94 */
95 use: ["nib"],
96
97 /**
98 * Add path(s) to the import lookup paths.
99 *
100 * @type {string[]}
101 * @default []
102 */
103 include: [path.join(__dirname, "src/styl/config")],
104
105 /**
106 * Import the specified Stylus files/paths.
107 *
108 * @type {string[]}
109 * @default []
110 */
111 import: ["nib", path.join(__dirname, "src/styl/mixins")],
112
113 /**
114 * Define Stylus variables or functions.
115 *
116 * @type {Array|Object}
117 * @default {}
118 */
119 // Array is the recommended syntax: [key, value, raw]
120 define: [
121 ["$development", process.env.NODE_ENV === "development"],
122 ["rawVar", 42, true],
123 ],
124 // Object is deprecated syntax (there is no possibility to specify "raw')
125 // define: {
126 // $development: process.env.NODE_ENV === 'development',
127 // rawVar: 42,
128 // },
129
130 /**
131 * Include regular CSS on @import.
132 *
133 * @type {boolean}
134 * @default false
135 */
136 includeCSS: false,
137
138 /**
139 * Resolve relative url()'s inside imported files.
140 *
141 * @see https://stylus-lang.com/docs/js.html#stylusresolveroptions
142 *
143 * @type {boolean|Object}
144 * @default { nocheck: true }
145 */
146 resolveURL: true,
147 // resolveURL: { nocheck: true },
148
149 /**
150 * Emits comments in the generated CSS indicating the corresponding Stylus line.
151 *
152 * @see https://stylus-lang.com/docs/executable.html
153 *
154 * @type {boolean}
155 * @default false
156 */
157 lineNumbers: true,
158
159 /**
160 * Move @import and @charset to the top.
161 *
162 * @see https://stylus-lang.com/docs/executable.html
163 *
164 * @type {boolean}
165 * @default false
166 */
167 hoistAtrules: true,
168
169 /**
170 * Compress CSS output.
171 * In the "production" mode is `true` by default
172 *
173 * @see https://stylus-lang.com/docs/executable.html
174 *
175 * @type {boolean}
176 * @default false
177 */
178 compress: true,
179 },
180 },
181 },
182 ],
183 },
184 ],
185 },
186};
187```
188
189#### `Function`
190
191Allows setting the options passed through to Stylus based off of the loader context.
192
193```js
194module.exports = {
195 module: {
196 rules: [
197 {
198 test: /\.styl/,
199 use: [
200 "style-loader",
201 "css-loader",
202 {
203 loader: "stylus-loader",
204 options: {
205 stylusOptions: (loaderContext) => {
206 // More information about available properties https://webpack.js.org/api/loaders/
207 const { resourcePath, rootContext } = loaderContext;
208 const relativePath = path.relative(rootContext, resourcePath);
209
210 if (relativePath === "styles/foo.styl") {
211 return {
212 paths: ["absolute/path/c", "absolute/path/d"],
213 };
214 }
215
216 return {
217 paths: ["absolute/path/a", "absolute/path/b"],
218 };
219 },
220 },
221 },
222 ],
223 },
224 ],
225 },
226};
227```
228
229### `sourceMap`
230
231Type: `Boolean`
232
233**webpack.config.js**
234
235```js
236module.exports = {
237 module: {
238 rules: [
239 {
240 test: /\.styl$/i,
241 use: [
242 "style-loader",
243 {
244 loader: "css-loader",
245 options: {
246 sourceMap: true,
247 },
248 },
249 {
250 loader: "stylus-loader",
251 options: {
252 sourceMap: true,
253 },
254 },
255 ],
256 },
257 ],
258 },
259};
260```
261
262### `webpackImporter`
263
264Type: `Boolean`
265Default: `true`
266
267Enables/Disables the default Webpack importer.
268
269This can improve performance in some cases.
270Use it with caution because aliases and `@import` at-rules starting with `~` will not work.
271
272**webpack.config.js**
273
274```js
275module.exports = {
276 module: {
277 rules: [
278 {
279 test: /\.styl/i,
280 use: [
281 "style-loader",
282 "css-loader",
283 {
284 loader: "stylus-loader",
285 options: {
286 webpackImporter: false,
287 },
288 },
289 ],
290 },
291 ],
292 },
293};
294```
295
296### `additionalData`
297
298Type: `String|Function`
299Default: `undefined`
300
301Prepends `Stylus` code before the actual entry file.
302In this case, the `stylus-loader` will not override the source but just **prepend** the entry's content.
303
304This is especially useful when some of your Stylus variables depend on the environment:
305
306> ℹ Since you're injecting code, this will break the source mappings in your entry file. Often there's a simpler solution than this, like multiple Stylus entry files.
307
308#### `String`
309
310```js
311module.exports = {
312 module: {
313 rules: [
314 {
315 test: /\.styl/,
316 use: [
317 "style-loader",
318 "css-loader",
319 {
320 loader: "stylus-loader",
321 options: {
322 additionalData: `@env: ${process.env.NODE_ENV};`,
323 },
324 },
325 ],
326 },
327 ],
328 },
329};
330```
331
332#### `Function`
333
334##### Sync
335
336```js
337module.exports = {
338 module: {
339 rules: [
340 {
341 test: /\.styl/,
342 use: [
343 "style-loader",
344 "css-loader",
345 {
346 loader: "stylus-loader",
347 options: {
348 additionalData: (content, loaderContext) => {
349 // More information about available properties https://webpack.js.org/api/loaders/
350 const { resourcePath, rootContext } = loaderContext;
351 const relativePath = path.relative(rootContext, resourcePath);
352
353 if (relativePath === "styles/foo.styl") {
354 return "value = 100px" + content;
355 }
356
357 return "value 200px" + content;
358 },
359 },
360 },
361 ],
362 },
363 ],
364 },
365};
366```
367
368##### Async
369
370```js
371module.exports = {
372 module: {
373 rules: [
374 {
375 test: /\.styl/,
376 use: [
377 "style-loader",
378 "css-loader",
379 {
380 loader: "stylus-loader",
381 options: {
382 additionalData: async (content, loaderContext) => {
383 // More information about available properties https://webpack.js.org/api/loaders/
384 const { resourcePath, rootContext } = loaderContext;
385 const relativePath = path.relative(rootContext, resourcePath);
386
387 if (relativePath === "styles/foo.styl") {
388 return "value = 100px" + content;
389 }
390
391 return "value 200px" + content;
392 },
393 },
394 },
395 ],
396 },
397 ],
398 },
399};
400```
401
402### `implementation`
403
404Type: `Function | String`
405
406The special `implementation` option determines which implementation of Stylus to use. Overrides the locally installed `peerDependency` version of `stylus`.
407
408#### Function
409
410**webpack.config.js**
411
412```js
413module.exports = {
414 module: {
415 rules: [
416 {
417 test: /\.styl/i,
418 use: [
419 "style-loader",
420 "css-loader",
421 {
422 loader: "stylus-loader",
423 options: {
424 implementation: require("stylus"),
425 },
426 },
427 ],
428 },
429 ],
430 },
431};
432```
433
434#### String
435
436**webpack.config.js**
437
438```js
439module.exports = {
440 module: {
441 rules: [
442 {
443 test: /\.styl/i,
444 use: [
445 "style-loader",
446 "css-loader",
447 {
448 loader: "stylus-loader",
449 options: {
450 implementation: require.resolve("stylus"),
451 },
452 },
453 ],
454 },
455 ],
456 },
457};
458```
459
460## Examples
461
462### Normal usage
463
464Chain the `stylus-loader` with the [`css-loader`](https://github.com/webpack-contrib/css-loader) and the [`style-loader`](https://github.com/webpack-contrib/style-loader) to immediately apply all styles to the DOM.
465
466**webpack.config.js**
467
468```js
469module.exports = {
470 module: {
471 rules: [
472 {
473 test: /\.styl$/,
474 use: [
475 {
476 loader: "style-loader", // creates style nodes from JS strings
477 },
478 {
479 loader: "css-loader", // translates CSS into CommonJS
480 },
481 {
482 loader: "stylus-loader", // compiles Stylus to CSS
483 },
484 ],
485 },
486 ],
487 },
488};
489```
490
491### Source maps
492
493To enable sourcemaps for CSS, you'll need to pass the `sourceMap` property in the loader's options. If this is not passed, the loader will respect the setting for webpack source maps, set in `devtool`.
494
495**webpack.config.js**
496
497```javascript
498module.exports = {
499 devtool: "source-map", // any "source-map"-like devtool is possible
500 module: {
501 rules: [
502 {
503 test: /\.styl$/,
504 use: [
505 "style-loader",
506 {
507 loader: "css-loader",
508 options: {
509 sourceMap: true,
510 },
511 },
512 {
513 loader: "stylus-loader",
514 options: {
515 sourceMap: true,
516 },
517 },
518 ],
519 },
520 ],
521 },
522};
523```
524
525### Using nib with stylus
526
527**webpack.config.js**
528
529```js
530module.exports = {
531 module: {
532 rules: [
533 {
534 test: /\.styl$/,
535 use: [
536 {
537 loader: "style-loader", // creates style nodes from JS strings
538 },
539 {
540 loader: "css-loader", // translates CSS into CommonJS
541 },
542 {
543 loader: "stylus-loader", // compiles Stylus to CSS
544 options: {
545 stylusOptions: {
546 use: [require("nib")()],
547 import: ["nib"],
548 },
549 },
550 },
551 ],
552 },
553 ],
554 },
555};
556```
557
558### Import JSON files
559
560Stylus does not provide resolving capabilities in the `json` function.
561Therefore webpack resolver does not work for `.json` files.
562Use [`stylus resolver`](#stylus-resolver).
563
564**index.styl**
565
566```styl
567// Suppose the file is located here `node_modules/vars/vars.json`
568json('vars.json')
569
570@media queries-small
571 body
572 display nope
573
574```
575
576**webpack.config.js**
577
578```js
579module.exports = {
580 module: {
581 rules: [
582 {
583 test: /\.styl$/,
584 use: [
585 "style-loader",
586 "css-loader",
587 {
588 loader: "stylus-loader",
589 options: {
590 stylusOptions: {
591 // Specify the path. where to find files
592 paths: ["node_modules/vars"],
593 },
594 },
595 },
596 ],
597 },
598 ],
599 },
600};
601```
602
603### In production
604
605Usually, it's recommended to extract the style sheets into a dedicated file in production using the [MiniCssExtractPlugin](https://github.com/webpack-contrib/mini-css-extract-plugin). This way your styles are not dependent on JavaScript.
606
607### webpack resolver
608
609Webpack provides an [advanced mechanism to resolve files](https://webpack.js.org/configuration/resolve/).
610The `stylus-loader` applies the webpack resolver when processing queries.
611Thus you can import your Stylus modules from `node_modules`.
612
613```styl
614@import 'bootstrap-styl/bootstrap/index.styl';
615```
616
617Using `~` is deprecated and can be removed from your code (**we recommend it**), but we still support it for historical reasons.
618Why you can removed it? The loader will first try to resolve `@import`/`@require` as relative, if it cannot be resolved, the loader will try to resolve `@import`/`@require` inside [`node_modules`](https://webpack.js.org/configuration/resolve/#resolve-modules).
619Just prepend them with a `~` which tells webpack to look up the [`modules`](https://webpack.js.org/configuration/resolve/#resolve-modules).
620
621```styl
622@import "~bootstrap-styl/bootstrap/index.styl";
623```
624
625It's important to only prepend it with `~`, because `~/` resolves to the home-directory.
626Webpack needs to distinguish between `bootstrap` and `~bootstrap`, because CSS and Styl files have no special syntax for importing relative files.
627Writing `@import "file"` is the same as `@import "./file";`
628
629### Stylus resolver
630
631If you specify the `paths` option, modules will be searched in the given `paths`.
632This is Stylus default behavior.
633
634**webpack.config.js**
635
636```js
637module.exports = {
638 module: {
639 rules: [
640 {
641 test: /\.styl/,
642 use: [
643 {
644 loader: "style-loader",
645 },
646 {
647 loader: "css-loader",
648 },
649 {
650 loader: "stylus-loader",
651 options: {
652 stylusOptions: {
653 paths: [path.resolve(__dirname, "node_modules")],
654 },
655 },
656 },
657 ],
658 },
659 ],
660 },
661};
662```
663
664### Extracting style sheets
665
666Bundling CSS with webpack has some nice advantages like referencing images and fonts with hashed urls or [hot module replacement](https://webpack.js.org/concepts/hot-module-replacement/) in development. In production, on the other hand, it's not a good idea to apply your style sheets depending on JS execution. Rendering may be delayed or even a [FOUC](https://en.wikipedia.org/wiki/Flash_of_unstyled_content) might be visible. Thus it's often still better to have them as separate files in your final production build.
667
668There are two possibilities to extract a style sheet from the bundle:
669
670- [`extract-loader`](https://github.com/peerigon/extract-loader) (simpler, but specialized on the css-loader's output)
671- [MiniCssExtractPlugin](https://github.com/webpack-contrib/mini-css-extract-plugin) (more complex, but works in all use-cases)
672
673## Contributing
674
675Please take a moment to read our contributing guidelines if you haven't yet done so.
676
677[CONTRIBUTING](./.github/CONTRIBUTING.md)
678
679## License
680
681[MIT](./LICENSE)
682
683[npm]: https://img.shields.io/npm/v/stylus-loader.svg
684[npm-url]: https://npmjs.com/package/stylus-loader
685[node]: https://img.shields.io/node/v/stylus-loader.svg
686[node-url]: https://nodejs.org
687[deps]: https://david-dm.org/webpack-contrib/stylus-loader.svg
688[deps-url]: https://david-dm.org/webpack-contrib/stylus-loader
689[tests]: https://github.com/webpack-contrib/stylus-loader/workflows/stylus-loader/badge.svg
690[tests-url]: https://github.com/webpack-contrib/stylus-loader/actions
691[cover]: https://codecov.io/gh/webpack-contrib/stylus-loader/branch/master/graph/badge.svg
692[cover-url]: https://codecov.io/gh/webpack-contrib/stylus-loader
693[chat]: https://img.shields.io/badge/gitter-webpack%2Fwebpack-brightgreen.svg
694[chat-url]: https://gitter.im/webpack/webpack
695[size]: https://packagephobia.now.sh/badge?p=stylus-loader
696[size-url]: https://packagephobia.now.sh/result?p=stylus-loader
Note: See TracBrowser for help on using the repository browser.