source: trip-planner-front/node_modules/postcss-import/README.md@ 76712b2

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

initial commit

  • Property mode set to 100644
File size: 6.4 KB
Line 
1# postcss-import
2
3[![Build](https://img.shields.io/travis/postcss/postcss-import/master)](https://travis-ci.org/postcss/postcss-import)
4[![Version](https://img.shields.io/npm/v/postcss-import)](https://github.com/postcss/postcss-import/blob/master/CHANGELOG.md)
5[![postcss compatibility](https://img.shields.io/npm/dependency-version/postcss-import/peer/postcss)](https://postcss.org/)
6
7> [PostCSS](https://github.com/postcss/postcss) plugin to transform `@import`
8rules by inlining content.
9
10This plugin can consume local files, node modules or web_modules.
11To resolve path of an `@import` rule, it can look into root directory
12(by default `process.cwd()`), `web_modules`, `node_modules`
13or local modules.
14_When importing a module, it will look for `index.css` or file referenced in
15`package.json` in the `style` or `main` fields._
16You can also provide manually multiples paths where to look at.
17
18**Notes:**
19
20- **This plugin should probably be used as the first plugin of your list.
21This way, other plugins will work on the AST as if there were only a single file
22to process, and will probably work as you can expect**.
23- This plugin works great with
24[postcss-url](https://github.com/postcss/postcss-url) plugin,
25which will allow you to adjust assets `url()` (or even inline them) after
26inlining imported files.
27- In order to optimize output, **this plugin will only import a file once** on
28a given scope (root, media query...).
29Tests are made from the path & the content of imported files (using a hash
30table).
31If this behavior is not what you want, look at `skipDuplicates` option
32- **If you are looking for glob, or sass like imports (prefixed partials)**,
33please look at
34[postcss-easy-import](https://github.com/trysound/postcss-easy-import)
35(which use this plugin under the hood).
36- Imports which are not modified (by `options.filter` or because they are remote
37 imports) are moved to the top of the output.
38- **This plugin attempts to follow the CSS `@import` spec**; `@import`
39 statements must precede all other statements (besides `@charset`).
40
41## Installation
42
43```console
44$ npm install postcss-import
45```
46
47## Usage
48
49Unless your stylesheet is in the same place where you run postcss
50(`process.cwd()`), you will need to use `from` option to make relative imports
51work.
52
53```js
54// dependencies
55const fs = require("fs")
56const postcss = require("postcss")
57const atImport = require("postcss-import")
58
59// css to be processed
60const css = fs.readFileSync("css/input.css", "utf8")
61
62// process css
63postcss()
64 .use(atImport())
65 .process(css, {
66 // `from` option is needed here
67 from: "css/input.css"
68 })
69 .then((result) => {
70 const output = result.css
71
72 console.log(output)
73 })
74```
75
76`css/input.css`:
77
78```css
79/* can consume `node_modules`, `web_modules` or local modules */
80@import "cssrecipes-defaults"; /* == @import "../node_modules/cssrecipes-defaults/index.css"; */
81@import "normalize.css"; /* == @import "../node_modules/normalize.css/normalize.css"; */
82
83@import "foo.css"; /* relative to css/ according to `from` option above */
84
85@import "bar.css" (min-width: 25em);
86
87body {
88 background: black;
89}
90```
91
92will give you:
93
94```css
95/* ... content of ../node_modules/cssrecipes-defaults/index.css */
96/* ... content of ../node_modules/normalize.css/normalize.css */
97
98/* ... content of css/foo.css */
99
100@media (min-width: 25em) {
101/* ... content of css/bar.css */
102}
103
104body {
105 background: black;
106}
107```
108
109Checkout the [tests](test) for more examples.
110
111### Options
112
113### `filter`
114Type: `Function`
115Default: `() => true`
116
117Only transform imports for which the test function returns `true`. Imports for
118which the test function returns `false` will be left as is. The function gets
119the path to import as an argument and should return a boolean.
120
121#### `root`
122
123Type: `String`
124Default: `process.cwd()` or _dirname of
125[the postcss `from`](https://github.com/postcss/postcss#node-source)_
126
127Define the root where to resolve path (eg: place where `node_modules` are).
128Should not be used that much.
129_Note: nested `@import` will additionally benefit of the relative dirname of
130imported files._
131
132#### `path`
133
134Type: `String|Array`
135Default: `[]`
136
137A string or an array of paths in where to look for files.
138
139#### `plugins`
140
141Type: `Array`
142Default: `undefined`
143
144An array of plugins to be applied on each imported files.
145
146#### `resolve`
147
148Type: `Function`
149Default: `null`
150
151You can provide a custom path resolver with this option. This function gets
152`(id, basedir, importOptions)` arguments and should return a path, an array of
153paths or a promise resolving to the path(s). If you do not return an absolute
154path, your path will be resolved to an absolute path using the default
155resolver.
156You can use [resolve](https://github.com/substack/node-resolve) for this.
157
158#### `load`
159
160Type: `Function`
161Default: null
162
163You can overwrite the default loading way by setting this option.
164This function gets `(filename, importOptions)` arguments and returns content or
165promised content.
166
167#### `skipDuplicates`
168
169Type: `Boolean`
170Default: `true`
171
172By default, similar files (based on the same content) are being skipped.
173It's to optimize output and skip similar files like `normalize.css` for example.
174If this behavior is not what you want, just set this option to `false` to
175disable it.
176
177#### `addModulesDirectories`
178
179Type: `Array`
180Default: `[]`
181
182An array of folder names to add to [Node's resolver](https://github.com/substack/node-resolve).
183Values will be appended to the default resolve directories:
184`["node_modules", "web_modules"]`.
185
186This option is only for adding additional directories to default resolver. If
187you provide your own resolver via the `resolve` configuration option above, then
188this value will be ignored.
189
190#### Example with some options
191
192```js
193const postcss = require("postcss")
194const atImport = require("postcss-import")
195
196postcss()
197 .use(atImport({
198 path: ["src/css"],
199 }))
200 .process(cssString)
201 .then((result) => {
202 const { css } = result
203 })
204```
205
206## `dependency` Message Support
207
208`postcss-import` adds a message to `result.messages` for each `@import`. Messages are in the following format:
209
210```
211{
212 type: 'dependency',
213 file: absoluteFilePath,
214 parent: fileContainingTheImport
215}
216```
217
218This is mainly for use by postcss runners that implement file watching.
219
220---
221
222## CONTRIBUTING
223
224* ⇄ Pull requests and ★ Stars are always welcome.
225* For bugs and feature requests, please create an issue.
226* Pull requests must be accompanied by passing automated tests (`$ npm test`).
227
228## [Changelog](CHANGELOG.md)
229
230## [License](LICENSE)
Note: See TracBrowser for help on using the repository browser.