Open source PostCSS polyfill for the new src() function

CSS Values and Units Level 4 defines a src() function. This function works just like the old-school url() function, but without url()'s legacy parsing behavior that prevents the use of additional CSS functions like var() inside it.

This plugin polyfills the src() function by compiling it to an equivalent url(), getting rid of the quotes around the string if possible. For example:

body {
  background: src("http://www.example.com/pinkish.gif");
}

is transformed into:

body {
  background: url(http://www.example.com/pinkish.gif);
}

Although this plugin doesn't natively polyfill CSS variables, it can be used with other polyfills like postcss-custom-properties to make it possible to include build-time variable values in url()s. But make sure you run postcss-src last in your plugin chain!

For example:

/* With both postcss-custom-properties and postcss-src: */

:root {
  --pinkish: "http://www.example.com/pinkish.gif";
}

body {
  background: src(var(--pinkish));
}

is transformed into:

body {
  background: url(http://www.example.com/pinkish.gif);
}

Usage

Add postcss-src to your project:

npm install postcss-custom-properties --save-dev

Use postcss-src as a PostCSS plugin:

const postcss = require('postcss');
const postcssSrc = require('postcss-src);

postcss([
  postcssSrc(/* plugin options */)
]).process(css /*, PostCSS options */);

Options

allowNativeSrc

By default, if postcss-src encounters a src() that it can't safely convert to a url() (such as src(var(--foo))), it will throw an error.

If this is true, it will emit the src() unchanged instead.

postcssSrc({
  allowNativeSrc: true,
});

For example, this throws an error by default but with allowNativeSrc: true it will be left unchanged.

/* Without postcss-custom-properties */

body {
  background: src(var(--foo));
}