PostCSS plugin for loading/including other files (transform @import
rules by inlining content) and quering/referring assets (referred in url()
functions).
Think of postcss-import
+ postcss-url
+ postcss-assets
.
This plugin can consume local files, node_modules
or web_modules
.
To resolve path of an @import
rule, it can look into root directory (by default process.cwd()
), web_modules
, node_modules
or local modules. When importing a module, it will looks for index.[css,sss,scss,sass,less]
or file referenced in package.json
in the style
, browser
, main
fields.
You can also provide manually multiples paths where to look at.
Notes:
- This plugin should probably be used as the first plugin of your list. This way, other plugins will work on the AST as if there were only a single file to process, and will probably work as you can expect.
- This plugin works great with
postcss-url plugin,
which will allow you to adjust assets
url()
(or even inline them) after inlining imported files. - In order to optimize output, this plugin will only import a file once.
Tests are made from the path & the content of imported files (using a hash
table).
If this behavior is not what you want, look at
skipDuplicates
option
$ npm install postcss-smart-import
If your stylesheets are not in the same place where you run postcss
(process.cwd()
), you will need to use from
option to make relative imports
work from input dirname.
// dependencies
var fs = require("fs")
var postcss = require("postcss")
var atImport = require("postcss-smart-import")
// css to be processed
var css = fs.readFileSync("css/input.css", "utf8")
// process css
postcss()
.use(atImport())
.process(css, {
// `from` option is required so relative import can work from input dirname
from: "css/input.css"
})
.then(function (result) {
var output = result.css
console.log(output)
})
Using this input.css
:
/* can consume `node_modules`, `web_modules` or local modules */
@import "cssrecipes-defaults"; /* == @import "./node_modules/cssrecipes-defaults/index.css"; */
@import "normalize.css"; /* == @import "./node_modules/normalize.css/normalize.css"; */
@import "css/foo.css"; /* relative to stylesheets/ according to `from` option above */
@import "css/bar.css" (min-width: 25em);
body {
background: black;
}
will give you:
/* ... content of ./node_modules/cssrecipes-defaults/index.css */
/* ... content of ./node_modules/normalize.css/normalize.css */
/* ... content of foo.css */
@media (min-width: 25em) {
/* ... content of bar.css */
}
body {
background: black;
}
Checkout tests for more examples.
Type: String
Default: process.cwd()
or dirname of
the postcss from
Define the root where to resolve path (eg: place where node_modules
are).
Should not be used that much.
Note: nested @import
will additionally benefit of the relative dirname of
imported files.
Type: String|Array
Default: []
A string or an array of paths in where to look for files.
Type: Function
Default: null
A function to transform the content of imported files. Take one argument (file
content) and should return the modified content or a resolved promise with it.
undefined
result will be skipped.
transform: function(css) {
return postcss([somePlugin]).process(css).then(function(result) {
return result.css;
});
}
Type: Array
Default: undefined
An array of plugins to be applied on each imported files.
Type: Function
Default: null
Function called after the import process. Take one argument (array of imported files).
Type: Function
Default: null
You can overwrite the default path resolving way by setting this option.
This function gets (id, basedir, importOptions)
arguments and returns full
path, array of paths or promise resolving paths.
You can use resolve for that.
Type: Function
Default: null
You can overwrite the default loading way by setting this option.
This function gets (filename, importOptions)
arguments and returns content or
promised content.
Type: Boolean
Default: true
By default, similar files (based on the same content) are being skipped.
It's to optimize output and skip similar files like normalize.css
for example.
If this behavior is not what you want, just set this option to false
to
disable it.
Type: Object
Default: null
An object with addDependency()
method, taking file path as an argument.
Called whenever a file is imported.
You can use it for hot-reloading in webpack postcss-loader
like this:
var smartImport = require("postcss-smart-import")
postcss: function(webpack) {
return [
smartImport({
addDependencyTo: webpack
/* Is equivalent to
onImport: function (files) {
files.forEach(this.addDependency)
}.bind(webpack)
*/
})
]
}
var postcss = require("postcss")
var smartImport = require("postcss-smart-import")
postcss()
.use(smartImport({
path: ["src/css"],
transform: require("css-whitespace")
}))
.process(cssString)
.then(function (result) {
var css = result.css
})
- ⇄ Pull requests and ★ Stars are always welcome.
- For bugs and feature requests, please create an issue.
- Pull requests must be accompanied by passing automated tests (
$ npm test
).
Copyright 2016
Sebastian Software GmbH