PostCSS Assets is an asset manager for CSS. It isolates stylesheets from environmental changes, gets image sizes and inlines files.
- Terms of use
- Installation
- Usage
- URL resolution
- Cachebuster
- Image dimensions
- Inlining files
- Full list of options
By using this project or its source code, for any purpose and in any shape or form, you grant your implicit agreement to all the following statements:
- You condemn Russia and its military aggression against Ukraine
- You recognize that Russia is an occupant that unlawfully invaded a sovereign state
- You support Ukraine's territorial integrity, including its claims over temporarily occupied territories of Crimea and Donbas
- You reject false narratives perpetuated by Russian state propaganda
Glory to Ukraine! 🇺🇦
npm install postcss-assets --save-devgulp.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/'));
});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.
These options isolate stylesheets from environmental changes.
To make PostCSS Assets search for files in specific directories, define load paths:
var options = {
loadPaths: ['fonts/', 'media/patterns/', 'images/']
};Example:
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:
body {
background: url('/media/patterns/foobar.jpg');
background: url('/images/icons/baz.png');
}If the root directory of your site is not where you execute PostCSS Assets, correct it:
var options = {
basePath: 'source/'
};PostCSS Assets would treat source directory as / for all URLs and load paths would be relative to it.
If the URL of your base path is not /, correct it:
var options = {
baseUrl: 'http://example.com/wp-content/themes/'
};To make resolved paths relative to the input file, set a flag:
var options = {
relative: true
};To relate to a particular directory, set it as a string:
var options = {
relative: 'assets/css'
};PostCSS Assets can bust assets cache:
var options = {
cachebuster: true
};Example:
body {
background: resolve('/images/icons/baz.png');
}PostCSS Assets will change urls depending on asset’s modification date:
body {
background: url('/images/icons/baz.png?14a931c501f');
}To define a custom cachebuster pass a function as an option:
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:
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
}
}
};PostCSS Assets calculates dimensions of PNG, JPEG, GIF, SVG and WebP images:
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:
body {
width: width('images/foobar.png', 2); /* 160px */
height: height('images/foobar.png', 2); /* 120px */
background-size: size('images/foobar.png', 2); /* 160px 120px */
}PostCSS inlines files to a stylesheet in Base64 encoding:
body {
background: inline('images/foobar.png');
}SVG files would be inlined unencoded, because then they benefit in size.
| 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 |
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
