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
<!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.
$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.
@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.
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.
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.
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
List all Gulp tutorials.