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