Repository files navigation

PostCSS plugin to transform@importrules by inlining content.

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 defaultprocess.cwd()),web_modules,node_modulesor local modules.When importing a module, it will look forindex.css or file referenced inpackage.json in thestyle ormain 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 fileto process, and will probably work as you can expect.
• Runningpostcss-url afterpostcss-import in your plugin chain will allow you to adjust assetsurl() (oreven inline them) after inlining imported files.
• In order to optimize output,this plugin will only import a file once ona given scope (root, media query...).Tests are made from the path & the content of imported files (using a hashtable).If this behavior is not what you want, look atskipDuplicates option
• If you are looking forGlob Imports, you can usepostcss-import-ext-glob to extend postcss-import.
• If you want to import remote sources, you can usepostcss-import-url with itsdataUrls plugin option to extend postcss-import.
• Imports which are not modified (byoptions.filter or because they are remoteimports) are moved to the top of the output.
• This plugin attempts to follow the CSS@import spec;@importstatements must precede all other statements (besides@charset).

$npm install -D postcss-import

Unless your stylesheet is in the same place where you run postcss(process.cwd()), you will need to usefrom option to make relative importswork.

// dependenciesconstfs=require("fs")constpostcss=require("postcss")constatImport=require("postcss-import")// css to be processedconstcss=fs.readFileSync("css/input.css","utf8")// process csspostcss().use(atImport()).process(css,{// `from` option is needed herefrom:"css/input.css"}).then((result)=>{constoutput=result.cssconsole.log(output)})

css/input.css:

/* remote urls are preserved */@import"https://example.com/styles.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"foo.css";/* relative to css/ according to `from` option above *//* all standard notations of the "url" value are supported */@importurl(foo-1.css);@importurl("foo-2.css");@import"bar.css" (min-width:25em);@import'baz.css' layer(baz-layer);body {background: black;}

will give you:

@import"https://example.com/styles.css";/* ... content of ../node_modules/cssrecipes-defaults/index.css *//* ... content of ../node_modules/normalize.css/normalize.css *//* ... content of css/foo.css *//* ... content of css/foo-1.css *//* ... content of css/foo-2.css */@media (min-width:25em) {/* ... content of css/bar.css */}@layer baz-layer {/* ... content of css/baz.css */}body {background: black;}

Checkout thetests for more examples.

Type:Function
Default:() => true

Only transform imports for which the test function returnstrue. Imports forwhich the test function returnsfalse will be left as is. The function getsthe path to import as an argument and should return a boolean.

Type:String
Default:process.cwd() ordirname ofthe postcssfrom

Define the root where to resolve path (eg: place wherenode_modules are).Should not be used that much.
Note: nested@import will additionally benefit of the relative dirname ofimported files.

Type:String|Array
Default:[]

A string or an array of paths in where to look for files.

Type:Array
Default:undefined

An array of plugins to be applied on each imported files.

Type:Function
Default:null

You can provide a custom path resolver with this option. This function gets(id, basedir, importOptions, astNode) arguments and should return a path, an array ofpaths or a promise resolving to the path(s). If you do not return an absolutepath, your path will be resolved to an absolute path using the defaultresolver.You can useresolve for this.

Type:Function
Default: null

You can overwrite the default loading way by setting this option.This function gets(filename, importOptions) arguments and returns content orpromised 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 likenormalize.css for example.If this behavior is not what you want, just set this option tofalse todisable it.

Type:Array
Default:[]

An array of folder names to add toNode's resolver.Values will be appended to the default resolve directories:["node_modules", "web_modules"].

This option is only for adding additional directories to default resolver. Ifyou provide your own resolver via theresolve configuration option above, thenthis value will be ignored.

Type:Boolean
Default:true

By defaultpostcss-import warns when an empty file is imported.
Set this option tofalse to disable this warning.

constpostcss=require("postcss")constatImport=require("postcss-import")postcss().use(atImport({path:["src/css"],})).process(cssString).then((result)=>{const{ css}=result})

postcss-import adds a message toresult.messages for each@import. Messages are in the following format:

{  type: 'dependency',  file: absoluteFilePath,  parent: fileContainingTheImport}

This is mainly for use by postcss runners that implement file watching.

• ⇄ 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).