1 | # postcss-import
|
2 |
|
3 | [![Unix Build status](https://img.shields.io/travis/postcss/postcss-import/master.svg?branch=master&label=unix%20build)](https://travis-ci.org/postcss/postcss-import)
|
4 | [![Windows Build status](https://img.shields.io/appveyor/ci/MoOx/postcss-import/master.svg?label=window%20build)](https://ci.appveyor.com/project/MoOx/postcss-import/branch/master)
|
5 | [![Version](https://img.shields.io/npm/v/postcss-import.svg)](https://github.com/postcss/postcss-import/blob/master/CHANGELOG.md)
|
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 looks 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 |
|
33 | ## Installation
|
34 |
|
35 | ```console
|
36 | $ npm install postcss-import
|
37 | ```
|
38 |
|
39 | ## Usage
|
40 |
|
41 | If your stylesheets are not in the same place where you run postcss
|
42 | (`process.cwd()`), you will need to use `from` option to make relative imports
|
43 | work from input dirname.
|
44 |
|
45 | ```js
|
46 | // dependencies
|
47 | var fs = require("fs")
|
48 | var postcss = require("postcss")
|
49 | var atImport = require("postcss-import")
|
50 |
|
51 | // css to be processed
|
52 | var css = fs.readFileSync("css/input.css", "utf8")
|
53 |
|
54 | // process css
|
55 | postcss()
|
56 | .use(atImport())
|
57 | .process(css, {
|
58 | // `from` option is required so relative import can work from input dirname
|
59 | from: "css/input.css"
|
60 | })
|
61 | .then(function (result) {
|
62 | var output = result.css
|
63 |
|
64 | console.log(output)
|
65 | })
|
66 | ```
|
67 |
|
68 | Using this `input.css`:
|
69 |
|
70 | ```css
|
71 | /* can consume `node_modules`, `web_modules` or local modules */
|
72 | @import "cssrecipes-defaults"; /* == @import "./node_modules/cssrecipes-defaults/index.css"; */
|
73 | @import "normalize.css"; /* == @import "./node_modules/normalize.css/normalize.css"; */
|
74 |
|
75 | @import "css/foo.css"; /* relative to stylesheets/ according to `from` option above */
|
76 |
|
77 | @import "css/bar.css" (min-width: 25em);
|
78 |
|
79 | body {
|
80 | background: black;
|
81 | }
|
82 | ```
|
83 |
|
84 | will give you:
|
85 |
|
86 | ```css
|
87 | /* ... content of ./node_modules/cssrecipes-defaults/index.css */
|
88 | /* ... content of ./node_modules/normalize.css/normalize.css */
|
89 |
|
90 | /* ... content of foo.css */
|
91 |
|
92 | @media (min-width: 25em) {
|
93 | /* ... content of bar.css */
|
94 | }
|
95 |
|
96 | body {
|
97 | background: black;
|
98 | }
|
99 | ```
|
100 |
|
101 | Checkout [tests](test) for more examples.
|
102 |
|
103 | ### Options
|
104 |
|
105 | #### `root`
|
106 |
|
107 | Type: `String`
|
108 | Default: `process.cwd()` or _dirname of
|
109 | [the postcss `from`](https://github.com/postcss/postcss#node-source)_
|
110 |
|
111 | Define the root where to resolve path (eg: place where `node_modules` are).
|
112 | Should not be used that much.
|
113 | _Note: nested `@import` will additionally benefit of the relative dirname of
|
114 | imported files._
|
115 |
|
116 | #### `path`
|
117 |
|
118 | Type: `String|Array`
|
119 | Default: `[]`
|
120 |
|
121 | A string or an array of paths in where to look for files.
|
122 |
|
123 | #### `transform`
|
124 |
|
125 | Type: `Function`
|
126 | Default: `null`
|
127 |
|
128 | A function to transform the content of imported files. Take one argument (file
|
129 | content) and should return the modified content or promise with it.
|
130 | `undefined` result will be skipped.
|
131 |
|
132 | #### `plugins`
|
133 |
|
134 | Type: `Array`
|
135 | Default: `undefined`
|
136 |
|
137 | An array of plugins to be applied on each imported files.
|
138 |
|
139 | #### `onImport`
|
140 |
|
141 | Type: `Function`
|
142 | Default: `null`
|
143 |
|
144 | Function called after the import process. Take one argument (array of imported
|
145 | files).
|
146 |
|
147 | #### `resolve`
|
148 |
|
149 | Type: `Function`
|
150 | Default: `null`
|
151 |
|
152 | You can overwrite the default path resolving way by setting this option.
|
153 | This function gets `(id, basedir, importOptions)` arguments and returns full
|
154 | path, array of paths or promise resolving paths.
|
155 | You can use [resolve](https://github.com/substack/node-resolve) for that.
|
156 |
|
157 | #### `load`
|
158 |
|
159 | Type: `Function`
|
160 | Default: null
|
161 |
|
162 | You can overwrite the default loading way by setting this option.
|
163 | This function gets `(filename, importOptions)` arguments and returns content or
|
164 | promised content.
|
165 |
|
166 | #### `skipDuplicates`
|
167 |
|
168 | Type: `Boolean`
|
169 | Default: `true`
|
170 |
|
171 | By default, similar files (based on the same content) are being skipped.
|
172 | It's to optimize output and skip similar files like `normalize.css` for example.
|
173 | If this behavior is not what you want, just set this option to `false` to
|
174 | disable it.
|
175 |
|
176 | #### `addDependencyTo`
|
177 |
|
178 | Type: `Function`
|
179 | Default: null
|
180 |
|
181 | Allow to generate and call a callback that take one argument, the object from
|
182 | which you need to call `addDependency` from.
|
183 | Called whenever a file is imported, handy in a webpack workflow.
|
184 | It's equivalent to `onImport` with the following code:
|
185 |
|
186 | ```js
|
187 | {
|
188 | onImport: function (files) {
|
189 | files.forEach(this.addDependency)
|
190 | }.bind(obj) // obj = the argument you should pass to `addDependencyTo()`
|
191 | }
|
192 | ```
|
193 |
|
194 | #### Example with some options
|
195 |
|
196 | ```js
|
197 | var postcss = require("postcss")
|
198 | var atImport = require("postcss-import")
|
199 |
|
200 | postcss()
|
201 | .use(atImport({
|
202 | path: ["src/css"]
|
203 | transform: require("css-whitespace")
|
204 | }))
|
205 | .process(cssString)
|
206 | .then(function (result) {
|
207 | var css = result.css
|
208 | })
|
209 | ```
|
210 |
|
211 | ---
|
212 |
|
213 | ## CONTRIBUTING
|
214 |
|
215 | * ⇄ Pull requests and ★ Stars are always welcome.
|
216 | * For bugs and feature requests, please create an issue.
|
217 | * Pull requests must be accompanied by passing automated tests (`$ npm test`).
|
218 |
|
219 | ## [Changelog](CHANGELOG.md)
|
220 |
|
221 | ## [License](LICENSE)
|