broccoli-sass-source-maps

4.3.0 verified Fri May 01 auth: no javascript

A Broccoli plugin for compiling SCSS and Sass files using Dart Sass or LibSass (via node-sass), with support for source maps (embedding sourcesContent). Version 4.3.0 is current, released May 2024, with slow release cadence (1-2 per year). Key differentiators: requires explicit Sass engine dependency, supports source maps by embedding sources, and offers options for silenceDeprecations and quietDeps. Designed for Ember and Broccoli-based build pipelines.

Common errors

error TypeError: compileSass is not a function ↓

cause Calling require('broccoli-sass-source-maps') without passing a Sass compiler.

fix

Replace require('broccoli-sass-source-maps') with require('broccoli-sass-source-maps')(require('sass'))

error Error: Cannot find module 'sass' ↓

cause Dart Sass not installed as a dependency.

fix

Run npm install --save-dev sass (or node-sass)

error TypeError: inputTrees is not iterable ↓

cause First argument must be an array of tree paths.

fix

Wrap the tree path in an array: [tree] instead of a single string.

Warnings

breaking Requires Node >= 10.24.1 ↓

fix Update Node to >= 10.24.1

deprecated LibSass (node-sass) is deprecated; use Dart Sass (sass) instead. ↓

fix Replace require('node-sass') with require('sass') and adjust options accordingly.

gotcha Source map paths are incorrect; only source content is embedded. ↓

fix Use a post-processing step to correct source map paths, or accept that source maps point to wrong files.

gotcha The factory function must be called with a Sass compiler instance immediately. ↓

fix Ensure you do require('broccoli-sass-source-maps')(require('sass')) not just require('broccoli-sass-source-maps').

Install

npm install broccoli-sass-source-maps

yarn add broccoli-sass-source-maps

pnpm add broccoli-sass-source-maps

Imports

default function
wrong
```
const compileSass = require('broccoli-sass-source-maps');
```
correct
```
const compileSass = require('broccoli-sass-source-maps')(require('sass'));
```
The factory function expects a Sass compiler instance (e.g., require('sass')). Forgetting to call with require('sass') breaks compilation.

compileSass (returned)

wrong

const outputTree = compileSass({inputTrees, inputFile: 'app.scss', outputFile: 'app.css', options});

correct

const outputTree = compileSass(inputTrees, 'app.scss', 'app.css', options);

Arguments are positional, not an options object. Common mistake: passing a single object instead of separate arguments.

Fiber option (Dart Sass)

wrong

const Fiber = require('fibers'); const compileSass = require('broccoli-sass-source-maps')(require('sass')({fiber: Fiber}));

correct

const compileSass = require('broccoli-sass-source-maps')(require('sass')); const Fiber = require('fibers'); const tree = compileSass([...], 'in.scss', 'out.css', {fiber: Fiber});

Fiber must be passed in the options hash, not to the require('sass') call. Passing it incorrectly does not speed up compilation.

Quickstart

Compiles SCSS with source maps using Dart Sass, demonstrating the required factory pattern and positional arguments.

const compileSass = require('broccoli-sass-source-maps')(require('sass'));
const inputTrees = ['styles', 'vendor'];
const inputFile = 'myapp/app.scss';
const outputFile = 'assets/app.css';
const options = { outputStyle: 'compressed', sourceMap: true };
const outputTree = compileSass(inputTrees, inputFile, outputFile, options);
module.exports = outputTree;