Sass --watch

What You’ll Learn

The Sass --watch flag (short: -w) keeps the compiler running and rebuilds CSS whenever you save. This page covers single-file watch, folder watch with colon pairs, --poll, npm scripts, and five practical examples.

What Is --watch?

Without flags, sass input.scss output.css compiles once and exits. With --watch, Sass compiles, then keeps listening for file changes and recompiles automatically—perfect while you learn or build a site.

• Recompile on every save of watched Sass (and many of its dependencies).
• Watch one file pair or an entire input folder.
• Leave the terminal open; stop with Ctrl+C.
• Pair with other flags like --style=compressed when you need them.

📝 Basic Syntax

From the Sass Basics guide: add the watch flag to a normal compile command.

# Watch one file → one CSS file
sass --watch input.scss output.css

# Same thing, short flag
sass -w input.scss output.css

Every time you save input.scss, Sass updates output.css and prints a short compile message.

📁 Watch Directories

To watch and output whole folders, use folder paths separated by a colon (: (many-to-many mode):

sass --watch app/sass:public/stylesheets

Sass watches everything in app/sass and writes CSS into public/stylesheets. Partials named with a leading underscore (_partial.scss) are not emitted as their own CSS files.

⚙️ --poll, --update & Friends

• --poll — only with --watch; manually check for changes when OS notifications fail (VMs, some network drives).
• --update — compile only out-of-date stylesheets once, then exit (not a long-running watcher).
• --style=compressed — still works while watching if you want smaller CSS during local checks.
• --stop-on-error — stop compiling more files after the first error (useful in strict setups).

📦 npm Script Pattern

Most projects wrap watch in package.json so teammates run one command:

{
  "scripts": {
    "sass": "sass scss:css",
    "sass:watch": "sass --watch scss:css"
  }
}

Then run npm run sass:watch during development.

Examples Gallery

Commands match the Sass guide and Dart Sass CLI. Open View Typical Log for sample terminal output.

sass --watch input.scss output.css

Compiled input.scss to output.css.

# After you save input.scss again...
Compiled input.scss to output.css.

sass --watch app/sass:public/stylesheets

Compiled app/sass/main.scss to public/stylesheets/main.css.
Compiled app/sass/home.scss to public/stylesheets/home.css.

# After you edit app/sass/home.scss...
Compiled app/sass/home.scss to public/stylesheets/home.css.

sass --watch --poll themes:public/css

Compiled themes/light.scss to public/css/light.css.

# Sass is polling for changes...
# After you save themes/dark.scss...
Compiled themes/dark.scss to public/css/dark.css.

# package.json → "sass:watch": "sass --watch scss:css"
npm run sass:watch

> my-site@1.0.0 sass:watch
> sass --watch scss:css

Compiled scss/main.scss to css/main.css.

sass --watch --style=compressed scss:dist/css

/* Readable (expanded) vs what --style=compressed aims for */
.button{padding:.5rem 1rem;background:#036;color:#fff}.button:hover{background:#024}

.button {
  padding: 0.5rem 1rem;
  background: #036;
  color: #fff;

  &:hover { background: #024; }
}

🚀 Real-World Use Cases

• Learning Sass — save SCSS, refresh the browser, see CSS update.
• Local site builds — sass --watch scss:public/css beside your static server.
• Multi-theme folders — watch themes:css for light/dark packs.
• Team npm scripts — document npm run sass:watch in the README.
• Flaky file systems — add --poll on VMs or network mounts.

⚠️ Common Pitfalls

• Wrong separator — folder mode needs input:output, not a space between two folders.
• Watching the wrong root — only directories you pass (and load paths) are watched reliably.
• Leaving watchers forever — stop with Ctrl+C; avoid dozens of forgotten terminals.
• Using --watch in CI — CI should one-shot compile; watch never exits on its own.
• Confusing --update with watch — --update compiles outdated files once, then exits.

💡 Best Practices