sass

A pure JavaScript implementation of Sass.

weekly downloads22.3M

versionv1.97.3

licenseMIT

categorystyling

stylescsssasspreprocessorcss

Overview

The sass package is the official pure JavaScript implementation of Dart Sass, a CSS preprocessor that extends standard CSS with programming constructs like variables, nesting, mixins, functions, and inheritance. It compiles .scss and .sass files into browser-ready CSS, enabling developers to write more maintainable and modular stylesheets.

With over 22 million weekly downloads, sass has become the standard choice for Sass compilation in JavaScript environments. Unlike its predecessor node-sass (which wrapped a C++ implementation), this package is compiled to pure JavaScript with zero native dependencies, eliminating installation headaches across different platforms and Node.js versions. It provides both synchronous and asynchronous APIs, along with a command-line interface for development workflows.

The package is actively maintained by the Sass core team and receives feature updates and bug fixes more rapidly than alternative implementations. It's used by developers building everything from small static sites to large-scale applications, and integrates seamlessly with build tools like webpack, Vite, Rollup, and Gulp. The implementation follows the official Sass specification, ensuring compatibility and consistent behavior across different environments.

Quick Start

typescript

import sass from 'sass';
import { writeFileSync } from 'fs';

// Compile a single SCSS file synchronously
const result = sass.compile('src/styles/main.scss', {
  style: 'compressed',
  sourceMap: true,
  loadPaths: ['node_modules', 'src/styles/abstracts']
});

writeFileSync('dist/main.css', result.css);
if (result.sourceMap) {
  writeFileSync('dist/main.css.map', JSON.stringify(result.sourceMap));
}

// Compile SCSS string with custom functions
const customResult = sass.compileString(`
  @use 'sass:math';
  
  $primary-color: #3498db;
  
  .button {
    background: adjust-color($primary-color, $lightness: 10%);
    padding: math.div(16px, 2) 24px;
    
    &:hover {
      background: $primary-color;
    }
  }
`, {
  functions: {
    'get-env($key)': (args) => {
      const key = args[0].assertString('key').text;
      return new sass.SassString(process.env[key] || '');
    }
  }
});

console.log(customResult.css);

Use Cases

Build tool integration: Incorporate Sass compilation into webpack, Vite, or Rollup configurations to automatically process .scss files during bundling, enabling component-scoped styles in modern JavaScript frameworks.

Design system development: Create reusable theme variables, mixins, and functions that can be shared across multiple projects, maintaining consistent branding and reducing duplication in large codebases.

Legacy codebase migration: Replace node-sass in existing projects to eliminate native dependency issues, especially when upgrading Node.js versions or deploying to environments with restricted compilation capabilities.

Static site generation: Use the Node.js API to compile stylesheets programmatically during static site builds with tools like Eleventy, Gatsby, or custom build scripts that need fine-grained control over CSS output.

Watch mode development: Run the CLI with --watch flag during local development to automatically recompile stylesheets on file changes, providing instant feedback without manual build triggering or complex task runners.

Pros & Cons

Pros

+Zero native dependencies makes installation reliable across all platforms and Node.js versions without compilation failures
+Actively maintained by Sass core team with fastest implementation of new Sass features and specification updates
+Pure JavaScript implementation enables easier debugging and integration with JavaScript tooling ecosystem
+Drop-in replacement for node-sass with compatible API, simplifying migration for existing projects
+Supports both modern SCSS syntax and indented Sass syntax with comprehensive feature parity

Cons

−Synchronous compilation can be 2-3x slower than node-sass for large stylesheets due to JavaScript vs C++ performance differences
−Asynchronous API is substantially slower than synchronous, making it impractical for most use cases despite non-blocking benefits
−Numeric precision defaults to 10 digits, which differs from LibSass and may cause subtle rounding differences in calculations
−Memory consumption can be higher than native implementations when processing very large codebases with thousands of files
−No built-in caching mechanism requires external tooling or manual cache implementation for optimal rebuild performance

Install

bash

npm install sass

bash

pnpm add sass

bash

bun add sass

Overview

Quick Start

typescript

import sass from 'sass';
import { writeFileSync } from 'fs';

// Compile a single SCSS file synchronously
const result = sass.compile('src/styles/main.scss', {
  style: 'compressed',
  sourceMap: true,
  loadPaths: ['node_modules', 'src/styles/abstracts']
});

writeFileSync('dist/main.css', result.css);
if (result.sourceMap) {
  writeFileSync('dist/main.css.map', JSON.stringify(result.sourceMap));
}

// Compile SCSS string with custom functions
const customResult = sass.compileString(`
  @use 'sass:math';
  
  $primary-color: #3498db;
  
  .button {
    background: adjust-color($primary-color, $lightness: 10%);
    padding: math.div(16px, 2) 24px;
    
    &:hover {
      background: $primary-color;
    }
  }
`, {
  functions: {
    'get-env($key)': (args) => {
      const key = args[0].assertString('key').text;
      return new sass.SassString(process.env[key] || '');
    }
  }
});

console.log(customResult.css);

Use Cases

Pros & Cons

Pros

+Zero native dependencies makes installation reliable across all platforms and Node.js versions without compilation failures
+Actively maintained by Sass core team with fastest implementation of new Sass features and specification updates
+Pure JavaScript implementation enables easier debugging and integration with JavaScript tooling ecosystem
+Drop-in replacement for node-sass with compatible API, simplifying migration for existing projects
+Supports both modern SCSS syntax and indented Sass syntax with comprehensive feature parity

Cons

−Synchronous compilation can be 2-3x slower than node-sass for large stylesheets due to JavaScript vs C++ performance differences
−Asynchronous API is substantially slower than synchronous, making it impractical for most use cases despite non-blocking benefits
−Numeric precision defaults to 10 digits, which differs from LibSass and may cause subtle rounding differences in calculations
−Memory consumption can be higher than native implementations when processing very large codebases with thousands of files
−No built-in caching mechanism requires external tooling or manual cache implementation for optimal rebuild performance