SassMerge tool

Node.js library which is responsible for concatenating and optimizing SASS/SCSS/CSS files for further parsing. It allows output target as either sass (indented syntax) or scss, but it will resolve and convert both meanwhile. It will go through all @imports and inline them inside single file.

Requirements

This library depends on sass-convert (which is required for conversion between types), so you need to install Ruby Sass gem. Also, because it's using some new JavaScript syntax, you should have Node.js 9+ installed.

Installation

• Install on machine Ruby with Sass gem (gem install sass)
• Run npm install @talixo/sass-merge --save

Examples

You can find examples in examples directory, for now it is:

• basic.js - basic example with some simple benchmarking
• watcher.js - example of watcher which also resolves URLs

CLI

Usage: sass-merge --input FILE_PATH --output FILE_PATH [option(s)]

Options:
  --help          Show help                                            [boolean]
  --version       Show version number                                  [boolean]
  --binary, -b    sass-convert executable file
                               [string] [default: "/usr/local/bin/sass-convert"]
  --target, -t    Type of file which will be generated
                                     [choices: "scss", "sass"] [default: "scss"]
  --input, -i     Input file to optimize for use             [string] [required]
  --output, -o    Path where result should be stored         [string] [required]
  --optimize      Unsafe optimizations                [boolean] [default: false]
  --watch, -w     Should watch for file changes?      [boolean] [default: false]
  --polling       Should use polling for watchers?    [boolean] [default: false]
  --colors, -c    Should color watcher output?         [boolean] [default: true]
  --manifest, -m  Manifest file path for url() mapping                  [string]
  --public, -p    Public path of manifest files           [string] [default: ""]
  --encoding      default encoding to use                               [string]

Node.js API reference

SassMerge

Merging files is as simple as:

const SassMerge = require('sass-merge')

const inputStylesheetPath = "src/styles/main.scss"
const options = {}

const merger = new SassMerge(inputStylesheetPath, options)

merger.build().then(console.log, console.error)

Available methods

| Name | Example | Description |--------------------------------------------------|-----------------------------------------------|----------------------------------- | build() : Promise<string, Error> | const stylesheet = await merger.build() | Build merged stylesheet | build(cache: object) : Promise<string, Error> | const cache = {}; await merger.build(cache) | Build merged stylesheet with cache. cache object will be mutated to store data between builds. | clean() : void | merger.clean() | Clean cache of resolved file paths

Options schema

| Name | Default value | Description |---------------------------------------|--------------------------------|------------- | target | "scss" | target output: "scss" or "sass" | resolveUrl | - | resolver for url(address) clauses; either: map of files mapping, JSON file path with such map or function which will build it | publicPath | - | when resolveUrl is files mapping or JSON file path, this path will be added as prefix for mapped file path | removeUnnecessaryWhitespaces | true | should remove unnecessary whitespaces, so end file will be smaller? | optimizeRedundantVariables | false | should remove redundant variables? see Limitations section | optimizeRedundantFunctionsAndMixins | false | should remove redundant functions and mixins? see Limitations section | cacheFilePaths | true | should cache resolved file paths or rebuild them each time? | resolveUrlsStartingWithSlash | false | should be enabled, when i.e. you have absolute URLs used, and you want to resolve them using resolveUrl (example: background-image: url("/Users/rangoo/Projects/image.png")) | globalDirectories | node_modules near input file | directories where should be files searched for as well | globalPrefixes | [ "", "~" ] | prefixes which means that file may be in global directory | extensions | [ "", ".scss", ".sass", ".css", "/index.scss", "/index.sass", "/index.css" ] | extensions which should be automatically resolved | maxBuffer | 500 * 1024 | max buffer for child process; you may need to increase it for bigger files | binary | global sass-convert | path to sass-convert executable file | usePolling | false | should use polling for watchers? (slower, but it's required on some environments) | encoding | - | default file encoding passed to sass-convert

SassMergeWatcher

Sometimes you may need to watch for file changes to update your code. You can obtain watcher using createWatcher() method:

const watcher = merger.createWatcher()

watcher.on('run', () => console.log('Building stylesheet...'))
watcher.on('ready', ({ stylesheet, took }) => console.log('Built stylesheet in ' + took + 'ms'))
watcher.on('error', ({ error, took }) => console.log('Build failed after ' + took + 'ms', error.message))

watcher.run()

Available events

SassMergeWatcher implements EventEmitter, so you can use methods like on(eventName, callback) or once(eventName, callback) to watch for events.

| Event name | Arguments | Description |------------|----------------------------------------|--------------- | run | Cause of running (file system event) | Build has started | ready | { stylesheet: string, took: number } | Build has been finished successfully | error | { error: Error, took: number } | Build has failed | stop | - | Watcher has been stopped

Available methods

It has EventEmitter methods like on and once. Also:

| Name | Example | Description |-------------------|-------------------|----------------------------------- | run() : Promise | watcher.run() | Start build and watch for files changes | stop() : void | watcher.stop() | Stop watching for files | clean() : void | watcher.clean() | Clean cache of resolved and converted files

Limitations

This tool is not parsing SCSS/SASS files, it is working on regular expressions instead to make it faster. Unfortunately, it may cause some unexpected problems, mostly with nested code.

Known problems

• optimizeRedundantVariables may incorrectly detect redundancy for nested variables with same names
• optimizeRedundantFunctionsAndMixins may incorrectly detect redundancy for nested functions/mixins with same names
• CSS files are neither parsed nor validated, so they may contain target code (sass or scss)

Changelog

• 0.1.15 - resolve //host.com/filePath URLs correctly (without protocol)
• 0.1.14 - fix problems with resolving absolute paths with resolveUrlsStartingWithSlash option
• 0.1.13 - add resolveUrlsStartingWithSlash option
• 0.1.12 - fix problems with empty single-line comments (without any character inside)
• 0.1.11 - add possibility to pass default file encoding
• 0.1.10 - fix issues with cache, so files are invalidated correctly
• 0.1.9 - remove unnecessary logging
• 0.1.8 - fix removing redundant variables, to not include code behind
• 0.1.7 - fix resolving paths of advanced URLs (with query strings and hashes)
• 0.1.6 - fix resolving URLs of not existing files (with manifest file)
• 0.1.5 - add possibility to use polling
• 0.1.4 - improve watcher, to watch files in case of error as well
• 0.1.3 - fix multiple imports in SASS syntax
• 0.1.2 - added CLI executable sass-merge command
• 0.1.1 - fix nested @imports for target: "sass"
• 0.1.0 - initial version