PostCSS plugin to manage assets
npm install postcss-assetsbash
npm install postcss-assets --save-dev
`
Usage
-----
$3
`js
gulp.task('assets', function () {
var postcss = require('gulp-postcss');
var assets = require('postcss-assets');
return gulp.src('source/*.css')
.pipe(postcss([assets({
loadPaths: ['images/']
})]))
.pipe(gulp.dest('build/'));
});
`
$3
`js
var assets = require('postcss-assets');
grunt.initConfig({
postcss: {
options: {
processors: [
assets({
loadPaths: ['images/']
})
]
},
dist: { src: 'build/*.css' }
},
});
`
Note: all of the listed options below are parameters for the `assets` object, not the top level postcss options object.
URL resolution
--------------
These options isolate stylesheets from environmental changes.
$3
To make PostCSS Assets search for files in specific directories, define load paths:
`js
var options = {
loadPaths: ['fonts/', 'media/patterns/', 'images/']
};
`
Example:
`css
body {
background: resolve('foobar.jpg');
background: resolve('icons/baz.png');
}
`
PostCSS Assets would look for the files relative to the source file, then in load paths, then in the base path. If it succeed, it would resolve a true URL:
`css
body {
background: url('/media/patterns/foobar.jpg');
background: url('/images/icons/baz.png');
}
`
$3
If the root directory of your site is not where you execute PostCSS Assets, correct it:
`js
var options = {
basePath: 'source/'
};
`
PostCSS Assets would treat source directory as / for all URLs and load paths would be relative to it.
$3
If the URL of your base path is not /, correct it:
`js
var options = {
baseUrl: 'http://example.com/wp-content/themes/'
};
`
$3
To make resolved paths relative to the input file, set a flag:
`js
var options = {
relative: true
};
`
To relate to a particular directory, set it as a string:
`js
var options = {
relative: 'assets/css'
};
`
Cachebuster
-----------
PostCSS Assets can bust assets cache:
`js
var options = {
cachebuster: true
};
`
Example:
`css
body {
background: resolve('/images/icons/baz.png');
}
`
PostCSS Assets will change urls depending on asset’s modification date:
`css
body {
background: url('/images/icons/baz.png?14a931c501f');
}
`
To define a custom cachebuster pass a function as an option:
`js
var options = {
cachebuster: function (filePath, urlPathname) {
return fs.statSync(filePath).mtime.getTime().toString(16);
}
};
`
If the returned value is falsy, no cache busting is done for the asset.
If the returned value is an object the values of pathname and/or query are used to generate a cache busted path to the asset.
If the returned value is a string, it is added as a query string.
The returned values for query strings must not include the starting ?.
Busting the cache via path:
`js
var options = {
cachebuster: function (filePath, urlPathname) {
var hash = fs.statSync(filePath).mtime.getTime().toString(16);
return {
pathname: path.dirname(urlPathname)
+ '/' + path.basename(urlPathname, path.extname(urlPathname))
+ hash + path.extname(urlPathname),
query: false // you may omit this one
}
}
};
`
Image dimensions
----------------
PostCSS Assets calculates dimensions of PNG, JPEG, GIF, SVG and WebP images:
`css
body {
width: width('images/foobar.png'); / 320px /
height: height('images/foobar.png'); / 240px /
background-size: size('images/foobar.png'); / 320px 240px /
}
`
To correct the dimensions for images with a high density, pass it as a second parameter:
`css
body {
width: width('images/foobar.png', 2); / 160px /
height: height('images/foobar.png', 2); / 120px /
background-size: size('images/foobar.png', 2); / 160px 120px /
}
`
Inlining files
--------------
PostCSS inlines files to a stylesheet in Base64 encoding:
`css
body {
background: inline('images/foobar.png');
}
`
SVG files would be inlined unencoded, because then they benefit in size.
Full list of options
--------------------
| Option | Description | Default |
|:--------------|:----------------------------------------------------------------------------------|:--------|
| basePath | Root directory of the project. | . |
| baseUrl | URL of the project when running the web server. | / |
| cachebuster | If cache should be busted. Pass a function to define custom busting strategy. | false |
| loadPaths | Specific directories to look for the files. | [] |
| relative | Directory to relate to when resolving URLs. When true, relates to the input file. When false, disables relative URLs. | false |
| cache | When true, if the input file not been modifed, use the results before cached. | false` |