Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 39 ยท Tooling and Build

The Sass CLI, Watch Mode and Source Maps

Install Sass and compile from the command line: file and folder mapping, --watch, output styles, load paths, source maps, quiet flags and npm scripts, with a live compiler.

Browsers cannot read Sass. Something must turn .scss into .css before the page loads, and the simplest "something" is the Sass command-line program. Even if you later use Vite or webpack, understanding the CLI explains every option those tools pass through to the compiler. This lesson walks through installing Sass, compiling, watching, choosing an output style and using source maps.

Installing Sass

Dart Sass is the reference implementation, and the only one that is actively developed. It comes in several packages:

Package What it is
sass (npm) Pure JavaScript build. Works everywhere Node works, slower on large projects.
sass-embedded (npm) Same compiler as a native executable plus a JavaScript wrapper. Noticeably faster for big projects.
Standalone binary Download from the Dart Sass releases or brew install sass/sass/sass; no Node needed.

For web projects, add it as a development dependency so everyone on the team uses the same version:

Terminal
npm install --save-dev sass
npx sass --version

The older LibSass (the node-sass package) is deprecated and no longer receives features. It does not support @use, so if a tutorial tells you to npm install node-sass, install sass instead.

Compiling a file

The basic command takes an input file and an output file:

Terminal
sass src/main.scss dist/main.css

Without an output path, the CSS prints to the terminal. Sass writes a source map next to the output (main.css.map) and adds a /*# sourceMappingURL=main.css.map */ comment at the end of the CSS.

You can map whole folders by writing input:output pairs; every non-partial .scss file in the input folder is compiled to a same-named .css file in the output folder:

Terminal
sass src/scss:dist/css

Files whose names begin with an underscore are partials and are skipped, since they exist to be loaded by other files.

Watching for changes

Terminal
sass --watch src/scss:dist/css

The process stays running and recompiles whenever a file changes. It tracks dependencies: editing _buttons.scss recompiles every entry file that loads it. If an error occurs, the message prints, the CSS file is left as it was, and the watcher keeps going.

Useful related flags:

  • --update compiles only files that are out of date (newer sources than outputs).
  • --poll checks the file system for changes manually, which helps inside Docker or network drives where native file events do not arrive.
  • --no-stop-on-error keeps compiling the other files when one fails.

Output style

Terminal
sass --style=expanded src/main.scss         # default: readable, one declaration per line
sass --style=compressed src/main.scss       # minified: no whitespace or comments

Only two styles exist in Dart Sass (the older nested and compact styles were LibSass features). compressed strips whitespace and most comments, but it is not a full optimizer: it does not merge rules or remove unused CSS. For production, you normally pipe the result through a tool such as cssnano or Lightning CSS. Comments starting with /*! are kept in compressed mode, which is the place to put licence notices.

The live compiler

The editor below compiles with the same Dart Sass engine. Try both styles and look at the source map JSON.

Output styles and source maps

The mappings string is a compact code (base64 VLQ) saying "this span of CSS came from that line and column of which source". You never read it; DevTools does.

Source maps in practice

With a source map loaded, the browser's inspector shows _buttons.scss:14 instead of main.css:2803 when you click a rule. Source maps are on by default in the CLI. Options:

Terminal
sass --no-source-map src/main.scss dist/main.css      # skip the .map file
sass --embed-sources src/main.scss dist/main.css      # copy sources into the map
sass --embed-source-map src/main.scss dist/main.css   # put the map inside the CSS
sass --source-map-urls=absolute src/main.scss dist/main.css   # file:// URLs instead of relative

Guidelines:

  • Development: keep source maps on; they make debugging far faster.
  • Production: either skip them, or publish them only to an error-tracking service or behind authentication. A source map exposes your original source to anyone who requests it.
  • If DevTools shows the CSS file but not the Sass file, check that the .map file is served at the URL the comment names and that DevTools' "enable CSS source maps" setting is on.

Finding files: load paths

When you write @use "buttons", Sass looks relative to the current file first, then in each load path. Add one with -I or --load-path:

Terminal
sass --load-path=node_modules --load-path=src/shared src/main.scss dist/main.css

Now @use "bootstrap/scss/variables" resolves inside node_modules and @use "tokens" can find src/shared/_tokens.scss. Many bundlers set load paths for you; for the CLI, you set them yourself.

Reading from standard input

Terminal
echo '$c: red; a { color: $c }' | sass --stdin
sass --stdin --indented < styles.sass     # for the indented syntax

Handy for quick experiments and shell pipelines.

Noise control

Flag Effect
--quiet or -q Hides warnings (@warn and deprecations). @debug is hidden by --quiet too.
--quiet-deps Hides warnings that come from dependencies (files found via load paths).
--silence-deprecation=<id> Ignores one named deprecation.
--fatal-deprecation=<id> Turns that deprecation (or a whole version) into an error.
--no-charset Do not add @charset "UTF-8"; or a byte-order mark for non-ASCII output.
--no-unicode Plain ASCII error messages, helpful for log files.
--trace Full stack trace on errors, useful when reporting a bug.

--fatal-deprecation in CI is a smart way to keep a codebase ready for the next major version, which we discuss in migrating from @import.

npm scripts

Put the commands in package.json so nobody has to remember them:

JSON
{
  "scripts": {
    "sass": "sass --load-path=node_modules src/scss:dist/css",
    "sass:watch": "npm run sass -- --watch",
    "sass:build": "sass --style=compressed --no-source-map --load-path=node_modules src/scss:dist/css"
  }
}

Run npm run sass:watch while developing and npm run sass:build in your deploy step. The -- passes the extra --watch flag through to Sass.

Common problems

  • "Can't find stylesheet to import": wrong relative path or missing load path. Check the filename, the underscore and the folder.
  • Changes not picked up inside Docker: add --poll.
  • Different output on two machines: versions differ; pin the exact sass version in package.json.
  • Output has @charset "UTF-8";: it appears when your CSS contains non-ASCII characters (an emoji in content, for example). It is harmless and recommended.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does sass src/scss:dist/css do?

    A colon pairs an input folder with an output folder; partials starting with an underscore are skipped.
  2. 2. Which flag keeps Sass running and recompiles when files change?

    --watch stays running; --poll only changes how changes are detected.
  3. 3. Which output styles does Dart Sass offer?

    Dart Sass removed nested and compact; expanded is the default and compressed minifies.
  4. 4. Why might you avoid publishing source maps in production?

    A map contains (or points to) the original Sass; publish it only where intended.
  5. 5. What does --load-path=node_modules allow?

    Load paths are extra folders where Sass looks for files named in @use.

Summary

  • Install Dart Sass with npm i -D sass (or sass-embedded for speed); node-sass and LibSass are deprecated.
  • sass in.scss out.css compiles one file; sass src:dist compiles a folder; --watch rebuilds on change.
  • Dart Sass has expanded and compressed styles; compressed is not a full optimizer.
  • Source maps link CSS back to Sass for DevTools; keep them in development and be careful in production.
  • Use --load-path for shared folders and node_modules; use --quiet-deps and --fatal-deprecation to manage warnings; wrap commands in npm scripts.

Next: The JavaScript API