ZetCode

Gulp Sass

last modified November 15, 2026

In this article we show how to compile Sass to CSS with Gulp 5 and the gulp-sass plugin. We split the styles into partials, produce compressed CSS with source maps, and rebuild the stylesheet automatically whenever a source file changes.

Gulp

Gulp is a streaming task runner for Node.js. Its tasks read files with src, transform them with plugins chained by pipe, and write the results with dest. The basics are covered in the Gulp getting started tutorial.

Sass

Sass is a stylesheet language compiled to CSS. It adds variables, nesting, mixins, functions, and modules to CSS. Sass has two syntaxes: the indented syntax in .sass files, which uses indentation instead of braces, and SCSS in .scss files, which is a superset of CSS and the more common choice.

Files whose names start with an underscore, such as _variables.scss, are partials. They are not compiled on their own; other files load them with the @use rule. The reference implementation of the language is Dart Sass, distributed on npm as the sass package.

The gulp-sass plugin

The gulp-sass plugin compiles Sass files in a Gulp pipeline. It does not include a compiler; we pass it the compiler module when we create the plugin. The sass package is the one to use, since the older node-sass package, which used the deprecated LibSass, is no longer maintained.

Installing Gulp and gulp-sass

We create a Node.js project and install Gulp, the plugin, the Sass compiler, and the del package for deleting files.

We use Gulp 5.0.1, gulp-sass 6.0.1, and Dart Sass 1.108.2.

$ mkdir gulp-sass
$ cd gulp-sass
$ npm init -y
$ npm i -D gulp gulp-sass sass del
$ npm ls --depth=0
gulp-sass@1.0.0 /home/jano/Documents/prog/js/gulp-sass
├── del@9.0.1
├── gulp-sass@6.0.1
├── gulp@5.0.1
└── sass@1.108.2

Gulp Sass example

The example compiles the stylesheet of an HTML page with a table.

This is the project structure without the node_modules directory. The compiled stylesheet goes into the css directory, which Gulp creates.

.
├── gulpfile.mjs
├── index.html
├── package.json
├── package-lock.json
└── sass
    ├── main.scss
    └── partials
        └── _variables.scss
index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="stylesheet" href="css/main.css">
    <title>Bugs</title>
</head>
<body>

<div class="container">

    <h1>Bugs</h1>

    <table>
        <tr>
            <th>Bug name</th>
            <th>Description</th>
        </tr>
        <tr>
            <td>Assassin bug</td>
            <td>The assassin bug uses its short three-segmented beak to
                pierce its prey and eat it.</td>
        </tr>
        <tr>
            <td>Bed bug</td>
            <td>Bed bugs are parasitic insects that feed exclusively
                on blood.</td>
        </tr>
        <tr>
            <td>Carpet beetle</td>
            <td>Carpet beetle larvae damage natural fibres in carpets,
                furniture, clothing, and museum insect collections.</td>
        </tr>
        <tr>
            <td>Earwig</td>
            <td>Earwigs hide in small, moist crevices during the day and
                are active at night, feeding on insects and plants.</td>
        </tr>
    </table>

</div>

</body>
</html>

The page links the generated css/main.css file.

sass/partials/_variables.scss
$font-stack: Georgia, serif;
$head-colour: #cccccc;
$row-colour: #eeeeee;
$border-colour: #dddddd;
$container-width: 700px;
$first-col-width: 150px;

The partial defines the variables shared by the stylesheets.

sass/main.scss
@use 'partials/variables' as *;

div.container {
    margin: auto;
    font: 1.2em $font-stack;
    width: $container-width;
}

table {
    border: 1px solid $border-colour;
    border-collapse: collapse;

    tr:nth-child(odd) {
        background: $row-colour;
    }

    td:first-child {
        width: $first-col-width;
    }

    th {
        background-color: $head-colour;
    }
}

The @use rule loads the partial; the underscore and the extension are omitted. Without as *, the variables would have to be prefixed with the module name, as in variables.$font-stack. The nested rules inside table compile to descendant selectors.

gulpfile.mjs
import { src, dest, series } from 'gulp';
import * as dartSass from 'sass';
import gulpSass from 'gulp-sass';
import { deleteAsync } from 'del';

const sass = gulpSass(dartSass);

export function clean() {

    return deleteAsync(['css']);
}

export function styles() {

    return src('sass/**/*.scss')
        .pipe(sass())
        .pipe(dest('css'));
}

export default series(clean, styles);

The gulpfile is an ES module with a clean task, a styles task, and a default task that runs them in order.

import * as dartSass from 'sass';
import gulpSass from 'gulp-sass';

const sass = gulpSass(dartSass);

We import the Dart Sass compiler and pass it to gulpSass, which returns the plugin function.

return src('sass/**/*.scss')
    .pipe(sass())
    .pipe(dest('css'));

The glob matches all SCSS files in the sass directory tree. The plugin compiles each file and changes its extension to .css; partials are skipped, because they are meant to be loaded by other files.

export default series(clean, styles);

The default task first removes the old css directory and then compiles the stylesheets.

We run the default task and print the result. Only main.css is generated. The variables are replaced by their values and the nested rules are flattened.

$ npx gulp
[12:18:45] Using gulpfile ~/Documents/prog/js/gulp-sass/gulpfile.mjs
[12:18:45] Starting 'default'...
[12:18:45] Starting 'clean'...
[12:18:45] Finished 'clean' after 11 ms
[12:18:45] Starting 'styles'...
[12:18:45] Finished 'styles' after 47 ms
[12:18:45] Finished 'default' after 59 ms
$ ls css
main.css
$ cat css/main.css
div.container {
  margin: auto;
  font: 1.2em Georgia, serif;
  width: 700px;
}

table {
  border: 1px solid #dddddd;
  border-collapse: collapse;
}
table tr:nth-child(odd) {
  background: #eeeeee;
}
table td:first-child {
  width: 150px;
}
table th {
  background-color: #cccccc;
}

Compressed CSS and source maps

For production, we want compressed CSS. The plugin passes its options to the Sass compiler; the style option selects expanded (the default) or compressed output. The sourcemaps options of src and dest make Gulp write a source map, which lets the browser developer tools show the original SCSS line of each rule.

gulpfile.mjs
import { src, dest, series } from 'gulp';
import * as dartSass from 'sass';
import gulpSass from 'gulp-sass';
import { deleteAsync } from 'del';

const sass = gulpSass(dartSass);

export function clean() {

    return deleteAsync(['css']);
}

export function styles() {

    return src('sass/**/*.scss', { sourcemaps: true })
        .pipe(sass({ style: 'compressed' }))
        .pipe(dest('css', { sourcemaps: '.' }));
}

export default series(clean, styles);

Only the styles task changed. The '.' value writes the map as a separate file into the output directory.

In the output, the CSS is on one line, the colours are shortened, and a comment at the end refers to the source map. The map lists both main.scss and partials/_variables.scss as sources.

$ npx gulp
[12:18:45] Using gulpfile ~/Documents/prog/js/gulp-sass/gulpfile.mjs
[12:18:45] Starting 'default'...
[12:18:45] Starting 'clean'...
[12:18:45] Finished 'clean' after 10 ms
[12:18:45] Starting 'styles'...
[12:18:45] Finished 'styles' after 54 ms
[12:18:45] Finished 'default' after 66 ms
$ ls css
main.css
main.css.map
$ cat css/main.css
div.container{margin:auto;font:1.2em Georgia,serif;width:700px}table{border:1px solid #ddd;border-collapse:collapse}table tr:nth-child(odd){background:#eee}table td:first-child{width:150px}table th{background-color:#ccc}/*# sourceMappingURL=main.css.map */

Watching for changes

The watch function runs a task whenever a file matching a glob is added, changed, or deleted. Changes that come in quick succession are debounced, and if the task is still running, the next run is queued.

gulpfile.mjs
import { src, dest, series, watch } from 'gulp';
import * as dartSass from 'sass';
import gulpSass from 'gulp-sass';
import { deleteAsync } from 'del';

const sass = gulpSass(dartSass);

export function clean() {

    return deleteAsync(['css']);
}

export function styles() {

    return src('sass/**/*.scss', { sourcemaps: true })
        .pipe(sass({ style: 'compressed' }))
        .pipe(dest('css', { sourcemaps: '.' }));
}

function watchStyles() {

    watch('sass/**/*.scss', styles);
}

export const dev = series(clean, styles, watchStyles);

export default series(clean, styles);

The dev task builds the stylesheet once and then keeps watching the SCSS files.

function watchStyles() {

    watch('sass/**/*.scss', styles);
}

The watchStyles task is private, because it is not exported. The glob also covers the partials, so changing a variable recompiles main.css. The task never signals completion; the watcher keeps the process running until we stop it with Ctrl+C.

The private watchStyles task appears only as a part of dev.

$ npx gulp --tasks
Tasks for ~/Documents/prog/js/gulp-sass/gulpfile.mjs
├── clean
├─┬ default
│ └─┬ <series>
│   ├── clean
│   └── styles
├─┬ dev
│ └─┬ <series>
│   ├── clean
│   ├── styles
│   └── watchStyles
└── styles

While the watcher was running, we changed a colour in the partial, then misspelled $head-colour in main.scss, and then fixed the typo again. Each save started the styles task. The compile error is reported with the file, line, and column, and the watcher keeps running, so the next save builds the stylesheet again. The Details part of the error, which repeats the message, is shortened here.

Older gulpfiles attach .on('error', sass.logError) to the plugin to keep the watcher alive after a compile error. With Gulp 5 the watcher survives errors without it, and the handler only prints the error message a second time.

$ npx gulp dev
[12:18:26] Using gulpfile ~/Documents/prog/js/gulp-sass/gulpfile.mjs
[12:18:26] Starting 'dev'...
[12:18:26] Starting 'clean'...
[12:18:26] Finished 'clean' after 11 ms
[12:18:26] Starting 'styles'...
[12:18:26] Finished 'styles' after 54 ms
[12:18:26] Starting 'watchStyles'...
[12:18:28] Starting 'styles'...
[12:18:28] Finished 'styles' after 13 ms
[12:18:30] Starting 'styles'...
[12:18:30] 'styles' errored after 34 ms
[12:18:30] Error in plugin "gulp-sass"
Message:
    sass/main.scss
Undefined variable.
   ╷
22 │         background-color: $head-color;
   │                           ^^^^^^^^^^^
   ╵
  - 22:27  root stylesheet
Details:
...
[12:18:32] Starting 'styles'...
[12:18:32] Finished 'styles' after 18 ms

Source

gulp-sass on npm, Sass documentation, Sass @use rule, Gulp watch API

In this article we have compiled Sass to CSS with Gulp 5, gulp-sass, and Dart Sass, loaded variables from a partial with @use, generated compressed CSS with a source map, and rebuilt the stylesheet on every change with watch. See also the Gulp getting started and Gulp Terser tutorials.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Gulp tutorials.