Dart Sass setup and SCSS compilation guide

How_to_use_Dart_SASS.md

Dart Sass — Quick Reference

Releases: github.com/sass/dart-sass/releases

---

1. The Language & Its Syntaxes

Sass is the name of the CSS pre-processor language. It comes in two syntaxes:

Feature	Sass (Indented)	SCSS (Sassy CSS)
File extension	.sass	.scss
Look & feel	Like Python — uses indentation (tabs/spaces)	Like CSS — uses braces {} and semicolons ;
CSS compatibility	Cannot paste plain CSS into it	Superset of CSS — all valid CSS is valid SCSS
Popularity	Older, "classic" style	Standard / modern choice

Which syntax should you use?

Use SCSS. Because SCSS is a superset of CSS, you can take any .css file, rename it to .scss, and it works immediately — zero changes required.

---

2. Setup — Running Dart Sass on Windows

Dart Sass ships as a standalone bundle. The compiler lives at:

dart-sass\src\dart.exe          ← the Dart runtime
dart-sass\src\sass.snapshot     ← the compiled Sass program

Navigate to the src folder first:

cd /d "D:\%username%\Downloads\dart-sass-1.99.0-windows-x64\dart-sass\src"

Note: dart.exe sass.snapshot, dart.exe sass, and the wrapper sass are not equivalent — they differ in how and whether the Dart VM is invoked. See § 4 for the full breakdown.

---

3. Common Commands

All commands below use dart.exe sass.snapshot (equivalent to dart sass — see § 4).

Compile with compression (minified output)

dart.exe sass.snapshot --style=compressed scss:dist

Watch mode (auto-recompile on save)

dart.exe sass.snapshot --watch scss:dist

Compressed output, no source map

dart.exe sass.snapshot --no-source-map --style=compressed scss:dist

Absolute input/output paths

dart.exe sass.snapshot --style=compressed "C:\Users\YourName\Desktop\MyProject\scss":"C:\Users\YourName\Desktop\MyProject\dist"

Compile current directory → current directory (compressed)

dart.exe sass.snapshot --style=compressed .:.

Compile current directory → current directory (expanded/default style)

dart.exe sass.snapshot .:.

Compile current directory → current directory (no source map)

dart.exe sass.snapshot --no-source-map .:.

Compile with named input/output directories, no source map

dart.exe sass.snapshot --no-source-map "inputdir":"outputdir"

Compile a single file to a .min.css output (shell/bash)

dart.exe sass.snapshot --style=compressed "$f" "${f%.scss}.min.css"

Compile a single named file

dart.exe sass.snapshot --style=compressed "main.scss" "main.min.css"

Expanded style, no source map, current directory

dart sass.snapshot --style=expanded --no-source-map .:.

---

4. dart.exe sass.snapshot vs dart.exe sass vs just sass

These are not all equivalent. Understanding the difference requires knowing how the Dart Sass bundle is structured.

What's in the bundle

The standalone Dart Sass download ships with exactly three files:

dart-sass\
  sass             ← wrapper script (sass.bat on Windows / sass shell script on Unix)
  src\
    dart.exe       ← the Dart VM (runtime)
    sass.snapshot  ← the compiled Sass program (kernel/JIT snapshot)

Snapshot types — why this matters

The Dart VM supports two distinct snapshot formats:

Type	Extension (convention)	Run with	Description
Kernel / JIT snapshot	.snapshot	dart.exe	Compiled to Dart's intermediate bytecode; JIT-compiled at runtime by the full VM
AOT snapshot	.aot or none	dartaotruntime	Fully compiled to native machine code ahead of time; smaller, faster startup, but not portable

sass.snapshot is a kernel/JIT snapshot — it requires the full dart.exe VM to run. If you mistakenly try to run it with dartaotruntime, you get the error:

sass is not an AOT snapshot, it cannot be run with 'dartaotruntime'

The three ways to invoke Sass

:: ✅ Explicit and correct — runs the JIT snapshot directly via the Dart VM
dart.exe sass.snapshot --style=compressed .:.

:: ⚠️  Works, but only if the Dart VM happens to resolve 'sass' as 'sass.snapshot'
::    This is NOT guaranteed across all environments
dart.exe sass --style=compressed .:.

:: ✅ Recommended — the wrapper script handles everything for you
sass --style=compressed .:.

The wrapper script (sass.bat on Windows, sass on Unix) is the right tool to use from the command line. It internally calls dart.exe sass.snapshot with the correct paths — so you get the full Dart VM speed without having to manage paths yourself.

Summary

• Use dart.exe sass.snapshot when you are inside the src\ directory and want to invoke the compiler directly (e.g. in scripts where you can't rely on PATH).
• Use sass (the wrapper) for everyday command-line use — it's simpler and more portable.
• Never use dartaotruntime with sass.snapshot — it is not an AOT snapshot.

---

5. Flags / Options Cheat Sheet

Flag	Description
--style=compressed	Minified output — removes all whitespace
--style=expanded	Human-readable output (default)
--watch	Watch input files and recompile on change
--no-source-map	Skip generating .css.map files
input:output	Map an input file or directory to an output file or directory

---

6. Path Syntax

input:output

• Directory → directory: scss:dist or .:. or "C:\...\scss":"C:\...\dist"
• File → file: "main.scss":"main.min.css" or "main.scss" "main.min.css" (space also works)

Quotes are required whenever the path contains spaces.

colors.scss

$primary-color: #3498db
$accent-color: #e74c3c
$bg-color: #f4f4f4

@mixin flex-center
  display: flex
  justify-content: center
  align-items: center

main.scss

@use 'colors';

body {
  background-color: colors.$bg-color;
  font-family: sans-serif;
}

.container {
  @include colors.flex-center;
  height: 100vh;
  
  .card {
    background: white;
    padding: 2rem;
    border-top: 5px solid colors.$primary-color;
    
    h1 {
      color: colors.$accent-color;
    }
  }
}