gulp-cssimport

gulp-cssimport

Parses a CSS file, finds imports, grabs the content of the linked file and replaces the import statement with it.

INSTALL

npm install gulp-cssimport

USAGE

var gulp = require("gulp");
var cssimport = require("gulp-cssimport");
var options = {};
gulp.task("import", function() {
	gulp.src("src/style.css")
		.pipe(cssimport(options))
		.pipe(gulp.dest("dist/"));
}); 

OPTIONS

includePaths

Array, default: []
Additional paths to resolve imports.

skipComments

Boolean, default: true
gulp-cssimport plugin uses regular expressions which is fast but not solid as AST. If you have any unexpected result, missing imported content, etc. Try to disable this option.

filter

RegExp, default: null (no filter).
Process only files which match to regexp. Any other non-matched lines will be leaved as is.
Example:

var options = {
	filter: /^http:\/\//gi // process only http urls
};

matchPattern

String, glob pattern string. See minimatch for more details.

var options = {
	matchPattern: "*.css" // process only css
};
var options2 = {
	matchPattern: "!*.{less,sass}" // all except less and sass
};

Note: matchPattern will not be applied to urls (remote files, e.g. http://fonts.googleapis.com/css?family=Tangerine), only files.
Urls are matched by default. If you do not want include them, use filter option (it is applicable to all).

matchOptions

Object, minimatch options for matchPattern.

limit

Number, default 5000.
Defence from infinite recursive import.

transform

Function, default null
Transform function applied for each import path.
Signature:

(path: string, data: {match: string}) => string

Arguments:

• path - string, path in import statement
• object with data:
  • match - string, matched import expression

extensions

Deprecated, use matchPattern instead.
String or Array, default: null (process all). Case insensitive list of extension allowed to process. Any other non-matched lines will be leaved as is.
Examples:

var options = {
	extensions: ["css"] // process only css
};
var options = {
	extensions: ["!less", "!sass"] // all except less and sass
};

TIPS AND TRICKS

Be more precise and do not add to src importing file without necessary:

// main.css
@import "a.css";
@import "b.css";

If you will do gulp.src("*.css") gulp will read a.css and b.css, and plugin also will try to read these files. It is extra job.
Do instead: gulp.src("main.css")

Use filter option:
If you need exclude files from import, try use filter only option (it is faster) and avoid others.

POSTCSS

There are plugins for PostCSS which do same job or even better:

• postcss-import inlines the stylesheets referred to by @import rules
• postcss-import-url inlines remote files.

SIMILAR PROJECTS

https://npmjs.org/package/gulp-coimport/
https://npmjs.org/package/gulp-concat-css/
https://github.com/yuguo/gulp-import-css/
https://github.com/postcss/postcss-import
https://www.npmjs.com/package/combine-css/
https://github.com/suisho/gulp-cssjoin
https://github.com/jfromaniello/css-import
https://github.com/mariocasciaro/gulp-concat-css

KNOWN ISSUES

• Cannot resolve @import 'foo.css' (min-width: 25em);

TODO

• Cache

CHANGELOG

6.0 [1 Sep 2017]

• remove byte order mask from imported files

5.1 [13 Aug 2017]

• added option 'transform'

5.0 [20 Nov 2016]

• added option 'skipComments'

4.0 [6 Oct 2016]

• added option 'includePaths'

3.0 [28 Feb 2016]

• removed node streams support, now only gulp
• removed directory option
• added sourcemaps support
• fixed bogus destination bugs

2.0 [30 Jun 2015]

• changed parse algorithm
• can handle recursive import
• can handle minified css files
• added option 'matchPattern'

1.3 [14 Nov 2014]

• added option 'extensions'
• added option 'filter'

1.2 [15 Feb 2014]

• fixed processing urls

1.1 [15 Feb 2014]

• switched to through2
• process files asynchronously

1.0 [12 Feb 2014]

• first release