postcss
postcss-url
PostCSS plugin to rebase, inline or copy on url().
Installation
$ npm install postcss postcss-urlBasic example - rebase
// dependencies
const fs = require("fs")
const postcss = require("postcss")
const url = require("postcss-url")
// css to be processed
const css = fs.readFileSync("input.css", "utf8")
// process css
const output = postcss()
.use(url({
url: "rebase"
}))
.process(css, {
from: "src/stylesheet/index.css",
to: "dist/index.css"
})before:
.element {
background: url('images/sprite.png');
}after:
.element {
/* rebasing path by new destination */
background: url('../src/stylesheet/images/sprite.png');
}Inline
// postcss-url options
const options = {
url: 'inline'
};
postcss()
.use(url(options))
.process(css, {
from: "src/stylesheet/index.css",
to: "dist/index.css"
})before:
.element {
background: url('/images/sprite.png');
filter: url('/images/circle.svg');
}after:
.element {
/* inlined png as base64 */
background: url('data:image/png;base64,R0lGODlhAQABAJH/AP///wAAAP///wAAACH/C0FET0JFOklSMS4');
/* inlined svg as encodeURIComponent */
filter: url('data:image/svg+xml,%3Csvg xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%2F%3E');
}Copy
// postcss-url options
const options = {
url: 'copy',
// base path to search assets from
basePath: path.resolve('node_modules/bootstrap'),
// dir to copy assets
assetsPath: 'img',
// using hash names for assets (generates from asset content)
useHash: true
};
postcss()
.use(url(options))
.process(css, {
from: "src/stylesheet/index.css",
to: "dist/index.css"
})before:
.element {
background: url('/images/sprite.png');
}after:
.element {
/* copy 'sprite.png' from 'node_modules/bootstrap/images/' to 'dist/img/' */
/* and rename it by hash function */
background: url('img/a2ds3kfu.png');
}Multiple options
process first matched option by default.
multi: true in custom will processing with other options
const options = [
{ filter: '**/assets/copy/*.png', url: 'copy', assetsPath: 'img', useHash: true },
{ filter: '**/assets/inline/*.svg', url: 'inline' },
{ filter: '**/assets/**/*.gif', url: 'rebase' },
// using custom function to build url
{ filter: 'cdn/**/*', url: (asset) => `https://cdn.url/${asset.url}` }
];
postcss().use(url(options))Checkout tests for examples.
Options combinations
rebase- defaultassetsPath- directory to copy assets (relative totoor absolute)
inlinebasePath- path or array of paths to search assets (relative tofrom, or absolute)encodeType-base64,encodeURI,encodeURIComponentincludeUriFragment- include the fragment identifer at the end of the URImaxSize- file size in kbytesfallback-copy,rebaseor custom function for files >maxSizeignoreFragmentWarning- do not warn when an SVG URL with a fragment is inlinedoptimizeSvgEncode- reduce size of inlined svg (IE9+, Android 3+)
copybasePath- path or array of paths to search assets (relative tofrom, or absolute)assetsPath- directory to copy assets (relative totoor absolute)useHash- use filehash(xxhash) for naminghashOptions- options for hash function
custom {Function}multi- processing with other options
Options list
url
rebase - (default)
Allow you to fix url() according to postcss to and/or from options (rebase to to first if available, otherwise from or process.cwd()).
inline
Allow you to inline assets using base64 encoding. Can use postcss from option to find ressources.
copy
Allow you to copy and rebase assets according to postcss to, assetsPath and from options (assetsPath is relative to the option to).
url: {Function}
Custom transform function. Takes following arguments:
asseturl- original urlpathname- url pathname (url without search or hash)absolutePath- absolute path to assetrelativePath- current relative path to assetsearch- search fromurl, ex.?query=1from./image.png?query=1hash- hash fromurl, ex.#spriteLinkfrom../asset.svg#spriteLink
dirfrom- postcss option fromto- postcss option tofile- decl file path
options- postcss-url matched optionsdecl- related postcss declaration objectwarn- wrapped functionresult.warnfor currentdeclresult– postcss result object
And should return the transformed url. You can use this option to adjust urls for CDN.
maxSize
Specify the maximum file size to inline (in kbytes)
ignoreFragmentWarning
(default: false)
Do not warn when an SVG URL with a fragment is inlined. PostCSS-URL does not support partial inlining. The entire SVG file will be inlined. By default a warning will be issued when this occurs.
NOTE: Only files less than the maximum size will be inlined.
filter
A regular expression e.g. /\.svg$/, a minimatch string e.g. '**/*.svg' or a custom filter function to determine wether a file should be inlined.
fallback
The url fallback method to use if max size is exceeded or url contains a hash. Custom transform functions are supported.
includeUriFragment
(default: false)
Specifies whether the URL's fragment identifer value, if present, will be added to the inlined data URI.
basePath
Specify the base path or list of base paths where to search images from
assetsPath
(default: false)
If you specify an assetsPath, the assets files will be copied in that
destination
useHash
(default: false)
If set to true the copy method is going to rename the path of the files by a hash name
hashOptions
method
(default: xxhash32)
Hash method xxhash32|xxhash64 or custom function (accept file buffer)
shrink
(default: 8)
Result hash shrink count
append
(default: false)
Prepend the original filename in resulting filename
Contributing
Work on a branch, install dev-dependencies, respect coding style & run tests before submitting a bug fix or a feature.
$ git clone https://github.com/postcss/postcss-url.git
$ git checkout -b patch-1
$ npm install
$ npm test