Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 39 ยท Getting Started

Installing and Compiling Sass

Install Dart Sass with npm or a standalone binary, compile SCSS from the command line with --watch, and call the JavaScript API from your own code.

To use Sass in a real project you need the compiler on your machine. The good news: there is one official compiler, Dart Sass, and it can be installed several ways. Whichever you pick, you end up with a sass command that reads .scss files and writes .css files. This lesson shows each route, the most useful command-line flags, and the JavaScript API that tools and the examples in this tutorial are built on.

Installing Dart Sass

With npm (recommended for web projects). If your project already has a package.json, add Sass as a development dependency:

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

You can also install it globally with npm install -g sass. The npm package is pure JavaScript, so it runs anywhere Node.js runs. It needs a recent Node (the current releases require Node 20 or newer).

As a standalone program. Dart Sass is also published as a native executable that does not need Node. Download the archive for your operating system from the project's GitHub releases page, or use a package manager:

Terminal
brew install sass/sass/sass     # macOS and Linux (Homebrew)
choco install sass              # Windows (Chocolatey)
scoop install sass              # Windows (Scoop)

Avoid the old packages node-sass (LibSass) and ruby-sass. They are deprecated, no longer receive features, and do not understand @use. If a tutorial tells you to install node-sass, install sass instead.

Compiling a file

Create styles.scss:

SCSS
$brand: #0ea5e9;

body {
  color: $brand;

  a { text-decoration: none; }
}

Then compile it:

Terminal
sass styles.scss styles.css

Sass writes styles.css (and a source map, styles.css.map, which lets browser dev tools show the original SCSS line). Link the CSS from your HTML as usual:

HTML
<link rel="stylesheet" href="styles.css">

If you leave out the output path, Sass prints the CSS to the terminal, which is handy for quick experiments.

Watching for changes

Re-running the command after every edit gets old fast. The --watch flag keeps Sass running and recompiles whenever a file it depends on changes:

Terminal
sass --watch styles.scss styles.css

You can also compile whole folders. The input:output pair syntax maps a source folder to a destination folder, keeping file names:

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

Files whose names start with an underscore (partials, covered in Partials and @use) are not compiled on their own: they are only included by other files.

Useful command-line flags

Flag What it does
--watch Recompile when sources change
--style=compressed Minify the output (default is expanded)
--no-source-map Do not write .css.map files
--embed-sources Put the original SCSS inside the source map
--load-path=node_modules Add a folder where @use and @forward look for files
--indented Treat stdin input as the indented syntax
--stdin Read the source from standard input
--quiet-deps Hide deprecation warnings that come from dependencies
--error-css On error, still write a CSS file that shows the error
--update Only recompile files that changed since the last run

A common npm setup puts the commands in package.json:

JSON
{
  "scripts": {
    "sass": "sass --watch src/scss:public/css",
    "build:css": "sass --style=compressed --no-source-map src/scss:public/css"
  }
}

Run them with npm run sass while developing and npm run build:css before deploying. Tooling and build covers bundlers like Vite and webpack, which can do this for you.

The JavaScript API

The compiler is also a library. The two main functions are:

  • sass.compile(path, options) reads a file from disk (Node.js only).
  • sass.compileString(source, options) compiles a string. It works in the browser too, which is how the examples on this site run.

Both return an object with a css string and, if you ask for it, a sourceMap. Useful options are style ("expanded" or "compressed"), sourceMap: true, loadPaths, and logger.

Compile with the JavaScript API

Reading error messages

When something is wrong, Sass refuses to produce output and prints the file, line and column. Errors are friendly, so read them. The API throws a Sass Exception whose message contains the details and whose span holds the location.

What a Sass error looks like

The message says Undefined variable. (sassMessage is that text without terminal colors), and span holds the exact line and column. A missing semicolon, an unclosed brace or a typo in a mixin name each produce a similar pointer.

When you compile to a file, Sass (by default, see --error-css) writes the error into the generated CSS as a body::before message, so you see the problem in the browser even when you are not looking at the terminal.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command compiles styles.scss to styles.css?

    The sass command takes the input path followed by the output path.
  2. 2. What does the --watch flag do?

    --watch keeps the process running and rebuilds whenever a source file or one of its dependencies changes.
  3. 3. Which package should you install in a new project?

    The sass package is Dart Sass compiled to JavaScript. node-sass and ruby-sass are deprecated.
  4. 4. Which JavaScript API function can run in the browser?

    compile() reads files and needs Node.js. compileString() takes the source as text and works anywhere JavaScript runs.

Summary

  • Install Dart Sass with npm install --save-dev sass, Homebrew, Chocolatey, or a standalone download.
  • sass input.scss output.css compiles; --watch recompiles on change; src:dist maps folders.
  • --style=compressed minifies, and source maps let dev tools show your SCSS.
  • Partials (underscore-prefixed files) are not compiled alone.
  • The JavaScript API (compile, compileString) powers bundler plugins and the live examples here.
  • Error messages show the file, line and a description of the problem.

Next: SCSS and the indented syntax