PostCSS Assets is an asset manager for CSS. It isolates stylesheets from environmental changes, gets image sizes and inlines files.
!Unix Build Statustravis-badgetravis !Windows Build Statusappveyor-badgeappveyor !Coveragecoveralls-badgecoveralls
Table of contents
-----------------
Load paths
Base path
Base URL
Relative paths
Installation
------------
```bash
npm install postcss-assets --save-dev
```
Usage
-----
```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/'));
});
```
```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.
Load paths
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');
}
```
Base path
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.
Base URL
If the URL of your base path is not
/, correct it:
```js
var options = {
baseUrl: 'http://example.com/wp-content/themes/'
};
```
Relative paths
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 |
