node-sass-cache-busted-url v0.0.1

node-sass-cache-busted-url

Sass custom function to replace URLs with ones with cache buster strings. Usable in node-sass.

USAGE

Let case as below:

// example.scss

body {
  background: cache-busted-url("/images/bg.png") no-repeat;
}

// cache-busters.json
// expected to generate by programs like gulp-rev

{
  "/images/bg.png": "/images/bg-3d1fc66b0a4bb6af83ea234d1f510408.png",
  ...
}

JavaScript API

var sass = requrie("node-sass");
var cacheBustedUrl = require("node-sass-cache-busted-url");

// Generate cache buster object which has url as key and cache-busted url as value
var cacheBusters = require(./cache-busters.json);

// Determine function signature used in Sass file
var functionSignature = "cache-busted-url($url)";

// Apply cache busters
var bustersDefinedBuster = cacheBustedUrl.bind(null, cacheBusters);

// Render CSS with pass `functions` option
var compiled = sass.renderSync({
  file: "./example.scss",
  functions: {
    functionSignature: bustersDefinedBuster
  }
});
console.log(compiled.css.toString());
// body {
//   background: url("/images/bg-3d1fc66b0a4bb6af83ea234d1f510408.png") no-repeat; }

Command-line interface

node-sass accepts functions options to specify file which defines Sass custom functions.

At CLI, specify path to file which defines URL-cache busted URL mapping by environment variable CACHE_BUSTERS_PATH.

$ CACHE_BUSTERS_PATH=cache-busters.json \
  $(npm bin)/node-sass \
  --functions=$(npm root)/node-sass-cache-busted-url/custom-functions.js \
  example.scss
body {
  background: url("/images/bg-3d1fc66b0a4bb6af83ea234d1f510408.png") no-repeat; }

Customize function name

As advanced usage of library, you can change the name of Sass custom function. Let's use it as image-url function:

// example.scss

body {
  background: image-url("/images/bg.png") no-repeat;
}

// cache-busters.json

{
  "/images/bg.png": "/images/bg-3d1fc66b0a4bb6af83ea234d1f510408.png",
  ...
}

Then execute JavaScript. Note that the value of functionSignature is changed:

var sass = requrie("node-sass");
var cacheBustedUrl = require("node-sass-cache-busted-url");

// Specify cache busters file
var cacheBusters = require(./cache-busters.json);

// Determine function signature used in Sass file
var functionSignature = "image-url($url)";

// Apply cache busters
var bustersDefinedBuster = cacheBustedUrl.bind(null, cacheBusters);

// Render CSS with pass `functions` options
var compiled = sass.renderSync({
  file: "./example.scss",
  functions: {
    functionSignature: bustersDefinedBuster
  }
});
console.log(compiled.css.toString());
// body {
//   background: url("/images/bg-3d1fc66b0a4bb6af83ea234d1f510408.png") no-repeat; }

LICENSE

LGPLv3 or later. See LICENSE for details.