postcss-url

What is postcss-url?

The postcss-url npm package is a PostCSS plugin used to process URLs in CSS. It allows developers to adjust asset URLs, inline images, or copy assets to a different location during the build process.

What are postcss-url's main functionalities?

Rebasing URLs

This feature allows you to adjust URLs based on the output directory, ensuring that they are correct in the built CSS.

postcss([ require('postcss-url')({ url: 'rebase' }) ]) // This will rebase all URLs according to the destination directory

Inlining images

This feature enables the inlining of images into your CSS, reducing the number of HTTP requests needed for loading assets.

postcss([ require('postcss-url')({ url: 'inline' }) ]) // This will inline images as base64 data URIs

Copying assets

This feature allows you to copy assets from your source CSS to a specified directory, which can be useful for organizing your build output.

postcss([ require('postcss-url')({ url: 'copy', assetsPath: 'img' }) ]) // This will copy referenced assets to a specified directory

Other packages similar to postcss-url

cssnano

cssnano is a modular minifier for CSS that includes functionalities for optimizing and transforming values, which can include URL rebasing. It differs from postcss-url in that it is more focused on overall CSS optimization rather than just URL processing.

gulp-rev

gulp-rev is a gulp plugin for asset revisioning by appending content hash to filenames. It can rewrite asset references in CSS, which is similar to some of the functionalities of postcss-url, but it is designed to work within the gulp ecosystem.

README

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