Gulp plugin to parse CSS and add referenced fonts to the stream
npm install gulp-css-userefurl()s to the gulp file stream, and optionally transform their path.
npm install --save-dev gulp-css-useref
`
Usage
The following example will parse the CSS and pass the files referenced by url()s through.
`js
var gulp = require('gulp'),
cssUseref = require('gulp-css-useref');
gulp.task('default', function () {
return gulp.src('app/*.css')
.pipe(cssUseref())
.pipe(gulp.dest('dist'));
});
`
With options:
`js
var gulp = require('gulp'),
cssUseref = require('gulp-css-useref');
gulp.task('default', function () {
return gulp.src('app/*.css')
.pipe(cssUseref({ base: 'assets' }))
.pipe(gulp.dest('dist'));
});
`
API
$3
Returns a stream with the assets referenced by url()s in any CSS files added.
Options
$3
Type: string
Default: undefined
Optional micromatch style glob used to limit which assets are processed. If the path specified in url() doesn't match this glob, it won't be processed.
$3
Type: string
Default: ''
Optional base path where the plugin will copy images, fonts, and other assets it finds in CSS url() declarations. Only url() declarations with relative paths are processed. Each asset's sub-directory hierarchy will be maintained under the base path. Basically, sub-directories after the last ../ in the path will be kept (or the whole path if no ../ exists). For example, if the plugin is called with { base: 'dist' }, the image referred to by url("../../images/icons/icon.jpg") will be copied to dist/images/icons/icon.jpg.
By using a single base path, a build pipeline can output several built CSS files while organizing all their assets under one directory (e.g. under dist/ in dist/images/, dist/fonts/, etc.).
If base is not specified, assets will be copied by default to the same directory relative to gulp.dest as the source asset from gulp.src, maintaining the assets' sub-directory hierarchy. For example, if gulp is told to output to dist and base is not specified, the image referred to from app/css/index.css by url("../../images/icons/icon.jpg") (which resolves to images/icons/icon.jpg) will be copied to dist/images/icons/icon.jpg.
$3
Type: function
Default: undefined
Optional function that returns a transformed filesystem path to an asset file. Useful for adding revision hashes to filenames for cachebusting (e.g. image-a7f234e8d4.jpg), or handling special cases. The function is expected to be of the form given below:
`js
/**
* Transforms the paths to which asset files will be copied
*
* @param {string} newAssetFile - Relative path to which asset would be copied by default
* @param {string} cssFilePathRel - Relative path to the CSS file that referenced the asset
* @param {string} urlMatch - The contents of the url() in the CSS file
* @param {object} options - The options hash passed into gulp-css-useref
* @returns {string} - Transformed Relative path to which asset will be copied
*/
pathTransform: function(newAssetFile, cssFilePathRel, urlMatch, options) {
// ... transform newAssetFile ...
return newAssetFile;
}
`
Credits
gulp-css-useref` reuses code and ideas from