@squirrel-forge/build-scss

Simple sass wrapper including some useful configuration options and extended features like package support and loading files as base64 encoded strings for font and image inclusion. Made to be compatible with node ^10.0.0, might work on higher versions, only partially tested.

Installation

npm i @squirrel-forge/build-scss

cli usage

If you installed globally with the -g option.

build-scss target -b --boolean --str=str,...
build-scss source target -b --boolean --str=str,...

For local installations use npx to run the build-scss executable.

npx build-scss ...

Arguments

The source argument can be a single file path or folder. The target argument must be a directory and will be created if it does not exist.

Using only one argument

the source argument is omitted and assumed to be the current working directory

1. target - Path to write rendered and processed css files

Using two arguments

1. source - Path from where to read, if a directory, sources are selected recursively with following options: { exclude : /\/_[^/]*\.(sass|scss)$/, extensions : /\.(sass|scss)/ }
2. target - Path to write rendered and processed css files

Options

A long option always override the value of a short option if both are used.

Short	Long	Type	Description
-p	--production	bool	Set env to production, strict, compressed, postcss and stats
-d	--development	bool	Set env to development, loose, no-postcss, with-map, experimental and stats in verbose
-e	--env	str	Set custom env name
-c	--compressed	bool	OutputStyle compressed
-m	--with-map	bool	Generate sourcemaps
	--no-postcss	bool	Disable postcss processing, the autoprefixer plugin won't run
-x	--experimental	bool / str, ...	Enable experimental features and load plugins, use without value or 'all' to enable all features, use comma separated list to enable specific features only
-o	--options	'no',str	Load options from this path, unless set to 'no', if not set regular checks apply
	--defaults	bool	Deploy plugins config to cwd or target directory
	--colors	int,int,int	Define verbose listing color kib limits, must be 3 integers > 0, default: 102400,204800,307200
-s	--stats	bool	Show stats output
-i	--verbose	bool	Show additional info, useful during development
-u	--loose	bool	Run in loose mode, disables the strict option and provides cleaner output when using @debug in your sass
-v	--version	bool	Show the application version

For fun, it's recommended to use following command options:

build-scss src dist -s -i -u -x

And no, this was not designed this way on purpose.

NPM scripts

When installed locally use following scripts.

...
"scripts": {
    "sass:render": "build-scss src/scss dev/css -d",
    "sass:publish": "build-scss src/scss dist/css -p",
}
...

Plugins and experimental features

Following all documented experimental features, the builtin shorthand names are only available when using the cli command.

build-scss src/scss/ dist/css -x={all|feature},...

Load files as base64 data url

Feature reference: b64

Provides a sass function base64load($source,$mime) that loads a file as data url, for more details check @squirrel-forge/sass-base64-loader.

Importing a package

Feature reference: pi

Provides a sass importer that will resolve package @import "~package" and @use "~package" statements, for more details check @squirrel-forge/sass-package-importer.

Custom plugins

You may load custom plugins with the -x or --experimental options, you may define plugins as reference or name:reference. Plugins are loaded with require and no further custom loading is used:

• Loading a plugin package: install the desired version of the package and use it's name as reference.
• Loading a local file path: use an absolute path or relative to process.cwd() as reference.

Plugin structure

Use the name:reference syntax and define the name in your plugin options config to customize your the options.

/**
 * Plugin factory sync
 * @param {Object} options - Plugin options
 * @param {Object} sassOptions - Sass options
 * @param {ScssBuilder} builder - Builder instance
 * @return {void}
 */
module.exports = function plugin( options, sassOptions, builder ) {
    
    // Set sass options, add sass plugins, extend postcss etc
};

Api usage

You can require the ScssBuilder class in your node script and run it, change internal options and extend it easily, look at the cli implementation and code comments to understand what to run in which order, currently there will be no extended documentation on the js api, since code comments should be sufficient to understand what works in which way.