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-url

Usage

// dependencies
var fs = require("fs")
var postcss = require("postcss")
var url = require("postcss-url")

// css to be processed
var css = fs.readFileSync("input.css", "utf8")

// process css
var output = postcss()
  .use(url({
    url: "rebase" // or "inline" or "copy"
  }))
  .process(css, {
    // "rebase" mode need at least one of those options
    // "inline" mode might need `from` option only
    // "copy" mode need `from` and `to` option to work
    from: "src/stylesheet/index.css"
    to: "dist/index.css"
  })
  .css

Checkout tests for examples.

Options

url

(default: "rebase")

url: "rebase"

Allow you to fix url() according to postcss to and/or from options (rebase to to first if available, otherwise from or process.cwd()).

url: "inline"

Allow you to inline assets using base64 syntax. Can use postcss from option to find ressources.

url: "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:

• URL – original url
• decl - related postcss declaration object
• from - from postcss option
• dirname – dirname of processing file
• to – from postcss option
• options – plugin options
• 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)

fallback

The url fallback method to use if max size is exceeded or url contains a hash. Custom transform functions are supported.

basePath

Specify the base path from where to search images

assetsPath

(default: false)

If you specify an assetsPath, the assets files would be copy in that destination

useHash

(default: false)

If is set in true the copy method is going to rename the path of the files by a hash name

---

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