0.1.15 • Published 3 years ago

@talixo/sass-merge v0.1.15

Weekly downloads
1
License
MIT
Repository
github
Last release
3 years ago

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

NameExampleDescription
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() : voidmerger.clean()Clean cache of resolved file paths

Options schema

NameDefault valueDescription
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
removeUnnecessaryWhitespacestrueshould remove unnecessary whitespaces, so end file will be smaller?
optimizeRedundantVariablesfalseshould remove redundant variables? see Limitations section
optimizeRedundantFunctionsAndMixinsfalseshould remove redundant functions and mixins? see Limitations section
cacheFilePathstrueshould cache resolved file paths or rebuild them each time?
resolveUrlsStartingWithSlashfalseshould 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"))
globalDirectoriesnode_modules near input filedirectories 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
maxBuffer500 * 1024max buffer for child process; you may need to increase it for bigger files
binaryglobal sass-convertpath to sass-convert executable file
usePollingfalseshould 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 nameArgumentsDescription
runCause 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:

NameExampleDescription
run() : Promisewatcher.run()Start build and watch for files changes
stop() : voidwatcher.stop()Stop watching for files
clean() : voidwatcher.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
0.1.15

3 years ago

0.1.14

3 years ago

0.1.13

3 years ago

0.1.12

3 years ago

0.1.11

3 years ago

0.1.10

3 years ago

0.1.9

3 years ago

0.1.8

3 years ago

0.1.7

3 years ago

0.1.6

3 years ago

0.1.5

3 years ago

0.1.4

3 years ago

0.1.3

3 years ago

0.1.2

3 years ago

0.1.1

3 years ago

0.1.0

3 years ago