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