@squirrel-forge/sass-base64-loader

A node sass function for importing files as base64 encoded strings built for the new sass js api must be used with the new sass package. Made to be compatible with node ^10.0.0, might work on higher versions, but currently not supported or tested.

Installation

npm i @squirrel-forge/sass-base64-loader

Usage

Sass function

Sass function signature: base64load($source,$mimetype)

• $source : string - Url, absolute or relative path (Note: Until sass context options are available, a relative path will be resolved relative to the Base64loadOptions.cwd option.)
• $mimetype : string - The $source file's mimetype (Note: This can be made optional by using the Base64loadOptions.detect or Base64loadOptions.remote option see remote file loading and mime detection for details.)

Returns : quoted string - Contains the given base64 encoded data uri

Source scss

:root {
  --image-loading-gif: #{url(base64load('cwd/images/loading.gif','image/gif'))};
}

Resulting css

:root {
  --image-loadgin-gif: url("data:image/gif;base64,R0lGODlhdgJ9AvYAAFZWVre3t0VFRdzc3DMzM...");
}

Plugin usage:

const sass = require( 'sass' );
const base64Loader = require( '@squirrel-forge/sass-base64-loader' );

// Classic way, calling the factory in place with options
const sassOptions = { functions : {} };
sassOptions.functions[ base64Loader.signature ] = base64Loader( /* null|Base64loadOptions */ ).callback;

// Destructuring the result object
const { signature, callback } = base64Loader( /* null|Base64loadOptions */ );
sassOptions.functions[ signature ] = callback;

// Plugin way, supply the sass options as second argument
// It will create the functions property if required and add the signature and function.
const sassOptions = {};
base64Loader( /* null|Base64loadOptions */, sassOptions );

// If not using the remote option you may use the sync compile which requires an explicit mimetype as second argument
const result = sass.compile( scssFilename, sassOptions );

// OR when using the async api you may use the remote option and automatically detect mimetypes
const result = await sass.compileAsync( scssFilename, sassOptions );

Options

/**
 * Base64load default options
 * @type {Object|Base64loadOptions}
 */
const BASE64LOAD_DEFAULT_OPTIONS = {
    detect : false,
    remote : false,
    cwd : null,
    cache : {},
};

/**
 * @typedef {Object} Base64loadOptions
 * @property {boolean} detect - Auto detect file mimetypes, default: false
 * @property {boolean} remote - Load files from http urls, default: false
 * @property {null|string} cwd - Base path for resolving relative paths, default: null > process.cwd()
 * @property {null|Object|Base64loadStringCache} cache - Caching object, default: {}
 */

Remote file loading and mimetype detection

Both options require use of the async sass.compileAsync api that supports async functions.

If you wish to load data from urls you need to set Base64loadOptions.remote = true

To automatically detect mimetypes set Base64LoadOptions.detect = true

Requirements

All dependencies are loose and will only be required at runtime if required through the Base64loadOptions.remote or Base64loadOptions.detect option.

Remote loading requires node-fetch@^2.x.x to function in a node@^10.x.x environment, on higher node versions you should be able to use newer versions.

Optional argument $mimetype

The $mimetype function argument becomes optional once you have enabled the Base64loadOptions.detect option or Base64loadOptions.remote loading and the async handler is used, but it requires file-type@^16.x.x to function in a node@^10.x.x environment, on higher node versions you should be able to use newer versions.

Issues

If you encounter any issues, please report here.

---

Check the sourcecode on github for extensive comments.