postcss-url

PostCSS plugin to rebase, inline or copy on url().

Installation

$ npm install postcss postcss-url

Basic 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 - default
- assetsPath - directory to copy assets (relative to to or absolute)
inline
- basePath - path or array of paths to search assets (relative to from, or absolute)
- encodeType - base64, encodeURI, encodeURIComponent
- includeUriFragment - include the fragment identifer at the end of the URI
- maxSize - file size in kbytes
- fallback - copy, rebase or custom function for files > maxSize
- ignoreFragmentWarning - do not warn when an SVG URL with a fragment is inlined
- optimizeSvgEncode - reduce size of inlined svg (IE9+, Android 3+)
copy
- basePath - path or array of paths to search assets (relative to from, or absolute)
- assetsPath - directory to copy assets (relative to to or absolute)
- useHash - use filehash(xxhash) for naming
- hashOptions - 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:

asset
- url - original url
- pathname - url pathname (url without search or hash)
- absolutePath - absolute path to asset
- relativePath - current relative path to asset
- search - search from url, ex. ?query=1 from ./image.png?query=1
- hash - hash from url, ex. #spriteLink from ../asset.svg#spriteLink
dir
- from - postcss option from
- to - postcss option to
- file - decl file path
options - postcss-url matched options
decl - related postcss declaration object
warn - wrapped function result.warn for current decl
result – 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

Changelog

License

License

postcss/postcss-url

ErrorLooks like something went wrong!

About

Resources

License

Stars

Watchers

Forks

Releases 43

Packages 0

Contributors 31

Languages

Error
Looks like something went wrong!

Packages