Skip to content

joneff/sass-build

Repository files navigation

sass-build

sass-build is an attempt to simplify the mundane task fo compiling sass. For what is worth, front-end developers probably don't need this package, yet all developers might find it useful due to it's simplicity and configuration.

Misc

sass-build was originally intended as a CLI tool, but since its guts are js (typescript to be precise), it can be used in js as well.

sass-build differs between compiling a file, which only returns the content and building a file, which will actually output it to disk.

sass-build works with an abstract set of sass options that are mapped to actual sass options, depending on the compiler and api used.

Installation

You can install sass-build using the following command:

npm install sass-build [--save-dev]

CLI Usage

By executing sass-build with no args, it will look for a file named sass.config.js and process it.

sass-build

To specify a different config use -c:

sass-build -c path/to/config.js

To compile a file, use -f:

sass-build -f path/to/file.scss

To build a file, supply the -d arg:

sass-build -f path/to/file.scss -d path/to/dest.css

To build multiple files, based on glob pattern, use -g:

sass-build -g "**/*.scss"

The default output location is ./dist. To change it, supply the -o arg:

sass-build -g "**/*.scss" -o "/path/to/output/dir"

To migrate a WebCompiler config to a sassBuild compatible one use:

# migrate compilerconfig.json to sass.config.js
sass-build --migrate-compiler-config

# specify which config to which output
sass-build --migrate-compiler-config -c "path/to/config.json" -d "path/to/config.js"

API Usage

const { sassBuild, sassBuildFiles } = require('sass-build');

let file = '/path/to/file.scss';
let outFile = '/path/to/outFile.css';

const output = {
    path: './my_dist', // specify output dir; defaults to './dist'
    filename: '[name:toLower].css' // specify output file name; defaults to '[name].css'
};
const options = {
    compiler: 'sass-embedded', // defaults to 'node-sass',
    api: 'modern', // defaults to 'legacy'
    sassOptions: {
        minify: true // defaults to false
    }
};

// single file
sassBuild(file, outFile); // compiles file and writes the result in outFile
sassBuild(file, outFile, options); // the same but with options

// Multiple files
sassBuildFiles('**/*.scss'); // compile all matched files to /dist
sassBuildFiles('**/*.scss', output ); // the same but with output options
sassBuildFiles('**/*.scss', output, options ); // the same but with options

Sass Config

Config files are the preferred way of working with sass build. Here is a sample one:

module.exports = {
    extends: [
        // use a predefined config:
        // * ~ import enabled
        // * postcss with autoprefixer and postcss-calc
        // * caching
        'sass-build:recommended'
    ],
    build: [
        {
            // use packages/default as the folder in which all lookup is based. default is process.cwd()
            cwd: 'packages/default',
            // path to source file, relative to cwd
            file: 'scss/all.scss',
            // path to out file, relative to cwd
            outFile: 'dist/all.css'
        },
        {
            cwd: 'packages/fluent',
            file: 'scss/all.scss',
            outFile: 'dist/all.css',
            // use different sass implementation
            compiler: 'sass-embedded',
            // use @use instead of @import syntax
            api: 'modern'
        }
    ]
};

Contributing?

Sure.