CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-node-sass

Node.js wrapper around libsass for compiling Sass and SCSS files to CSS

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

cli.mddocs/

Command Line Interface

Comprehensive CLI tool for build processes, file watching, and batch compilation with extensive configuration options for development and production workflows.

Capabilities

Basic Usage

# Compile single file
node-sass input.scss output.css

# Compile with options
node-sass --output-style compressed --source-map true input.scss output.css

# Watch for changes
node-sass --watch --recursive src/ --output dist/

# Get help
node-sass --help

# Get version
node-sass --version

Input/Output Options

Control how files are processed and where output is written.

# Input file (required unless using --data)
node-sass input.scss [output.css]

# Output directory (for --watch mode)
--output <dir>
-o <dir>

# Watch directory or file for changes
--watch
-w

# Recursively watch directories
--recursive
-r

# Read from stdin, write to stdout
echo "$primary: blue; .test { color: $primary; }" | node-sass --stdin

# Specify input as indented Sass syntax (not SCSS)
--indented-syntax
-i

Usage Examples:

# Basic file compilation
node-sass styles/main.scss dist/main.css

# Watch entire directory
node-sass --watch --recursive --output dist/ src/

# Process indented Sass
node-sass --indented-syntax styles/main.sass dist/main.css

# Pipe processing
cat input.scss | node-sass --stdin > output.css

Output Style Options

Control the formatting and compression of generated CSS.

# CSS output style
--output-style <style>
# Values: nested (default), expanded, compact, compressed

# Indentation type for output
--indent-type <type>
# Values: space (default), tab

# Indentation width (max 10)
--indent-width <number>
# Default: 2

# Line ending style
--linefeed <style>
# Values: cr, crlf, lf (default), lfcr

# Decimal precision for numbers
--precision <number>
# Default: 5

Usage Examples:

# Production build with compression
node-sass --output-style compressed --precision 3 src/main.scss dist/main.css

# Development build with readable output
node-sass --output-style expanded --indent-type space --indent-width 4 src/main.scss dist/main.css

# Custom line endings for Windows
node-sass --linefeed crlf --output-style expanded src/main.scss dist/main.css

Source Map Options

Generate and configure source maps for debugging.

# Generate source map
--source-map <true|false|path>

# Embed source contents in source map
--source-map-contents

# Embed source map as data URI in CSS
--source-map-embed

# Base path for source map URLs
--source-map-root <path>

# Omit source map URL comment from CSS
--omit-source-map-url
-x

Usage Examples:

# Generate source map file
node-sass --source-map true src/main.scss dist/main.css

# Custom source map location
node-sass --source-map dist/maps/main.css.map src/main.scss dist/main.css

# Inline source map
node-sass --source-map-embed src/main.scss dist/main.css

# Source map with embedded sources
node-sass --source-map true --source-map-contents src/main.scss dist/main.css

Import and Path Options

Configure how @import statements are resolved.

# Additional paths for @import resolution
--include-path <path>
# Can be used multiple times

# Follow symlinked directories
--follow

# Environment variable: SASS_PATH
# Colon-separated list of import paths
export SASS_PATH="/usr/local/sass:/home/user/sass"

Usage Examples:

# Multiple include paths
node-sass --include-path node_modules --include-path src/styles src/main.scss dist/main.css

# Using environment variable
export SASS_PATH="node_modules:src/partials"
node-sass src/main.scss dist/main.css

# Follow symlinks in watch mode
node-sass --watch --follow --recursive src/ --output dist/

Advanced Options

Extended functionality for debugging and customization.

# Include debug info in output
--source-comments

# Quiet mode - suppress output except errors
--quiet
-q

# Path to custom importer JavaScript file
--importer <path>

# Path to custom functions JavaScript file  
--functions <path>

# Ring bell on errors
--error-bell

Usage Examples:

# Debug build with comments
node-sass --source-comments --output-style expanded src/main.scss dist/main.css

# Quiet build process
node-sass --quiet --output-style compressed src/main.scss dist/main.css

# Custom functions and importers
node-sass --functions build/sass-functions.js --importer build/sass-importer.js src/main.scss dist/main.css

Watch Mode

Automatic recompilation when source files change.

# Watch single file
node-sass --watch input.scss --output output.css

# Watch directory
node-sass --watch --recursive src/ --output dist/

# Watch with specific options
node-sass --watch --output-style compressed --source-map true src/ --output dist/

Watch Mode Behavior:

  • Monitors source files and all imported dependencies
  • Automatically recompiles when any dependency changes
  • Outputs compilation status and timing information
  • Continues running until manually stopped (Ctrl+C)
  • Handles new files and deletions in watch directories
  • Preserves file structure in output directory

Usage Examples:

# Development workflow
node-sass --watch --recursive --output-style expanded --source-map true src/styles/ --output public/css/

# Production watch
node-sass --watch --output-style compressed --quiet src/main.scss --output dist/main.css

# Watch with custom configuration
node-sass --watch --recursive --include-path node_modules --functions build/functions.js src/ --output dist/

Custom Functions File

JavaScript file exporting custom Sass functions.

// Example functions file (sass-functions.js)
module.exports = {
  // Function with variable arguments
  'double(...)': function(args, done) {
    const value = args.getValue(0);
    const doubled = new sass.types.Number(
      value.getValue() * 2,
      value.getUnit()
    );
    done(doubled);
  },
  
  // Function with named arguments
  'add-alpha($color, $alpha)': function(color, alpha, done) {
    const newColor = new sass.types.Color(
      color.getR(),
      color.getG(),
      color.getB(),
      alpha.getValue()
    );
    done(newColor);
  }
};

Custom Importer File

JavaScript file exporting custom import resolution logic.

// Example importer file (sass-importer.js)
module.exports = function(url, prev, done) {
  // Handle npm: imports
  if (url.startsWith('npm:')) {
    const packageName = url.slice(4);
    try {
      const packagePath = require.resolve(packageName);
      done({ file: packagePath });
    } catch (error) {
      done(new Error(`Package not found: ${packageName}`));
    }
  }
  // Handle other custom imports
  else if (url.startsWith('http://') || url.startsWith('https://')) {
    // Could fetch remote files
    done(new Error('Remote imports not supported'));
  }
  // Let Sass handle normal imports
  else {
    done(null);
  }
};

Error Handling

CLI provides detailed error information for debugging.

# Error output includes:
# - Error message and description
# - File path and line/column numbers
# - Stack trace for JavaScript errors
# - Compilation context

# Exit codes:
# 0 - Success
# 1 - Compilation error
# 2 - Invalid arguments
# 3 - No input specified

Example Error Output:

Error: Invalid CSS after "  color: invalid-function(": expected expression (e.g. 1px, bold), was ")"
        on line 3 of src/main.scss
>>   color: invalid-function();
   ----------------------------^

Compilation failed in 15ms

Configuration via package.json

CLI options can be specified in package.json scripts.

{
  "scripts": {
    "sass:dev": "node-sass --watch --recursive --output-style expanded --source-map true src/styles/ --output public/css/",
    "sass:build": "node-sass --output-style compressed --source-map true src/styles/main.scss public/css/main.css",
    "sass:watch": "node-sass --watch --quiet --include-path node_modules src/main.scss --output dist/main.css"
  }
}

docs

cli.md

compilation.md

environment.md

index.md

types.md

tile.json