https://github.com/squirrel-forge/node-sass-base64-loader
A node sass function for importing files as base64 encoded strings built for the new sass js api.
https://github.com/squirrel-forge/node-sass-base64-loader
base64 base64-loader loader plugin sass sass-function
Last synced: 18 days ago
JSON representation
A node sass function for importing files as base64 encoded strings built for the new sass js api.
- Host: GitHub
- URL: https://github.com/squirrel-forge/node-sass-base64-loader
- Owner: squirrel-forge
- License: mit
- Created: 2022-01-25T00:16:51.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2022-02-12T11:06:31.000Z (over 4 years ago)
- Last Synced: 2025-10-04T23:30:58.583Z (8 months ago)
- Topics: base64, base64-loader, loader, plugin, sass, sass-function
- Language: JavaScript
- Homepage:
- Size: 20.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @squirrel-forge/sass-base64-loader
A node sass function for importing files as base64 encoded strings built for the new [sass js api](https://sass-lang.com/documentation/js-api) must be used with the new [sass](https://www.npmjs.com/package/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](#remote-file-loading-and-mimetype-detection) for details.)
**Returns** : *quoted string* - Contains the given base64 encoded data uri
#### Source scss
```scss
:root {
--image-loading-gif: #{url(base64load('cwd/images/loading.gif','image/gif'))};
}
```
#### Resulting css
```css
:root {
--image-loadgin-gif: url("data:image/gif;base64,R0lGODlhdgJ9AvYAAFZWVre3t0VFRdzc3DMzM...");
}
```
### Plugin usage:
```javascript
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
```javascript
/**
* 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](https://www.npmjs.com/package/node-fetch/v/2.6.7) 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](https://www.npmjs.com/package/file-type/v/16.5.3) 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](https://github.com/squirrel-forge/node-sass-base64-loader/issues).
---
Check the sourcecode on [github](https://github.com/squirrel-forge/node-sass-base64-loader) for extensive comments.