Supplies a set of functions to Sass that keep physical asset location details out of your source code. Also allows one to define a cache-busting policy or specify asset hosts by url.
This module supplies functions to a Sass compiler which can be called from your Sass code.
For example, the image-url
used here in place of url
adds build-time configuration to resolve the file to the proper location as seen from the web:
.some-selector {
background-image: image-url('cat.jpg');
}
NB Please note that the functions
option of dart-sass/node-sass is still experimental (>= v3.0.0).
This module provides some of the asset functions that came with Compass. Originally a fork of node-sass-asset-functions that was never merged.
image-url($filename: null, $only_path: false)
image-width($filename: null)
image-height($filename: null)
font-url($filename: null, $only-path: false)
font-files($filenames...)
inline-image($filename: null, $mime-type: null)
Basic usage is as easy as setting the functions
property:
const sass = require('sass');
const fiber = require('fibers');
const assetFunctions = require('@localnerve/sass-asset-functions');
sass.render({
functions: assetFunctions(/* options */),
file: scss_filename,
fiber, // dart-sass async render performance detail
[, options..]
}, function(err, result) { /*...*/ });
All options are optional.
name | type | description |
---|---|---|
sass |
Object | A reference to an alternate Sass compiler to use other than dart-sass (must expose types ). Defaults to undefined and a dart-sass reference is used |
images_path |
String | The build-time file path to images. Defaults to public/images |
fonts_path |
String | The build-time file path to fonts. Defaults to public/fonts |
http_images_path |
String | The path to images as seen from the web (nothing to do with http). Defaults to /images |
http_fonts_path |
String | The path to images as seen from the web (nothing to do with http). Defaults to /fonts |
asset_cache_buster |
Function | Signature (http_path, real_path, callback(new_url)). Supply to perform url transform for image-url or font-url , presumably for asset cache busting, but useful for any change to the url path (before fragment) |
asset_host |
Function | Signature (http_path, callback(new_url)). Supply to perform url transform for image-url or font-url , presumably to define an asset host, but useful for any change to the url before the path |
You can specify the paths to your resources using the following options (shown with defaults):
{
images_path: 'public/images', // local directory
fonts_path: 'public/fonts',
http_images_path: '/images', // web path
http_fonts_path: '/fonts'
}
So if your project images reside in public/img
at build-time instead of public/images
, you use it as follows:
const sass = require('sass');
const fiber = require('fibers');
const assetFunctions = require('@localnerve/sass-asset-functions');
sass.render({
functions: assetFunctions({
images_path: 'public/img',
http_images_path: '/images'
}),
file: scss_filename,
fiber,
[, options..]
}, function(err, result) { /*...*/ });
Example using the node-sass compiler using the new option sass
.
const sass = require('node-sass');
const assetFunctions = require('@localnerve/sass-asset-functions');
sass.render({
functions: assetFunctions({ sass }),
file: scss_filename,
[, options..]
}, function(err, result) { /*...*/ });
sass.render({
functions: assetFunctions({
asset_host: function(http_path, done){
done('http://assets.example.com');
// or use the supplied path to calculate a host
done(`http://assets${http_path.length % 4}.example.com`);
}
}),
file: scss_filename,
fiber,
[, options..]
}, function(err, result) { /*...*/ });
When this function returns a string, it's set as the query of the path. When returned an object, path
and query
will be used.
sass.render({
functions: assetFunctions({
asset_cache_buster: function(http_path, real_path, done){
done('v=123');
}
}),
file: scss_filename,
fiber,
[, options..]
}, function(err, result) { /*...*/ });
Here we include the file's hexdigest in the path, using the hexdigest
module.
For example, /images/myimage.png
would become /images/myimage-8557f1c9b01dd6fd138ba203e6a953df6a222af3.png
.
const sass = require('sass');
const fiber = require('fibers');
const path = require('path');
const fs = require('fs');
const hexdigest = require('hexdigest');
const assetFunctions = require('@localnerve/sass-asset-functions');
sass.render({
functions: assetFunctions({
asset_cache_buster: function(http_path, real_path, done){
hexdigest(real_path, 'sha1', function(err, digest) {
if (err) {
// an error occurred, maybe the file doesn't exist.
// Calling `done` without arguments will result in an unmodified path.
done();
} else {
const extname = path.extname(http_path);
const basename = path.basename(http_path, extname);
const new_name = `${basename}-${digest}${extname}`;
done({path: path.join(path.dirname(http_path), new_name), query: null});
}
});
}
}),
file: scss_filename,
fiber,
[, options..]
}, function(err, result) { /*...*/ });
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request