postcss-import
PostCSS plugin to transform
@import
rules by inlining content.
This plugin can consume local files, node modules or bower packages.
To resolve path of an @import
rule, it can look into root directory (by default process.cwd()
), node_modules
, web_modules
, bower_components
or local modules.
You can also provide manually multiples paths where to look at.
Notes:
- 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 on a given scope (root, media query...). Tests are made from the path & the content of imported files (using a hash table).
Installation
$ npm install postcss-import
Usage
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-import")
// css to be processed
var css = fs.readFileSync("css/input.css", "utf8")
// process css
var output = postcss()
.use(atImport())
.process(css, {
// `from` option is required so relative import can work from input dirname
from: "css/input.css"
})
.css
console.log(output)
Using this input.css
:
/* can consume `node_modules`, `web_modules`, `bower_components` or local modules */
@import "cssrecipes-defaults"; /* == @import "./node_modules/cssrecipes-defaults/index.css"; */
@import "normalize.css/normalize"; /* == @import "./bower_components/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/my-css-on-npm/index.css */
/* ... content of ./bower_components/my-css-on-bower/index.css */
/* ... content of foo.css */
@media (min-width: 25em) {
/* ... content of bar.css */
}
body {
background: black;
}
Checkout tests for more examples.
Options
root
Type: String
Default: process.cwd()
Define the root where to resolve path (eg: place where node_modules
and bower_components
are). Should not be used that much.
path
Type: String|Array
Default: process.cwd()
or dirname of the postcss from
A string or an array of paths in where to look for files.
Note: nested @import
will additionally benefit of the relative dirname of imported files.
async
Type: Boolean
Default: false
Allow to enable PostCSS async API usage. Before enabling this, check that your runner allow async usage. Note: this is not enabling async fs read yet.
transform
Type: Function
Default: null
A function to transform the content of imported files. Take one argument (file content) & should return the modified content.
plugins
Type: Array
Default: undefined
An array of plugins to be applied on each imported file.
encoding
Type: String
Default: utf8
Use if your CSS is encoded in anything other than UTF-8.
onImport
Type: Function
Default: null
Function called after the import process. Take one argument (array of imported files).
glob
Type: Boolean
Default: false
Set to true
if you want @import rules to parse glob patterns.
resolve
Type: Function
Default: null
You can overwrite the default path resolving way by setting this option, using the resolve.sync(id, opts)
signature that resolve.sync has.
Example with some options
var postcss = require("postcss")
var atImport = require("postcss-import")
var css = postcss()
.use(atImport({
path: ["src/css"]
transform: require("css-whitespace")
}))
.process(cssString)
.css
Contributing
Work on a branch, install dev-dependencies, respect coding style & run tests before submitting a bug fix or a feature.
$ git clone https://github.com/postcss/postcss-import.git
$ git checkout -b patch-1
$ npm install
$ npm test