Gulp clean
last modified November 15, 2026
In this article we delete the output directory of a Gulp 5 build with the
del package. We show why stale files are a problem, add a clean task in front of the
build with series, preview a deletion, keep selected files, and look at the safety
check of the package. We also compare it with the standard fs.rm function.
Why clean the output
A build writes files into a directory, but it never deletes files that it wrote the last time.
When we rename or remove a source file, its old output stays in the directory and is
deployed together with the new files. These stale files cause bugs that are hard to find: a page
that loads a script that no longer has a source, or a stylesheet that is kept alive by a forgotten copy.
The solution is to delete the output directory at the start of every build. Gulp has no built-in
function for that, but the del package does it well.
Installing the project
We create a project and install Gulp and del. Since version 7 the package is an
ES module, which works with the gulpfile.mjs that we use in all the tutorials.
$ mkdir gulp-clean $ cd gulp-clean $ npm init -y $ npm i -D gulp del $ mkdir src $ echo a > src/a.txt $ echo b > src/b.txt
The example project
The build copies the text files from src into dist. The
gulpfile also has the clean tasks that we use in the next sections.
import { src, dest, series } from 'gulp';
import { deleteAsync } from 'del';
import { rm } from 'node:fs/promises';
export function build() {
return src('src/*.txt')
.pipe(dest('dist'));
}
export function clean() {
return deleteAsync('dist');
}
export const rebuild = series(clean, build);
export async function preview() {
const paths = await deleteAsync(['dist/**', '!dist'], { dryRun: true });
console.log('would delete:', paths);
}
export async function keep() {
const paths = await deleteAsync(['dist/**', '!dist', '!dist/keep.txt']);
console.log('deleted:', paths);
}
export async function outside() {
await deleteAsync('../gulp-rename/dist');
}
export async function forced() {
const paths = await deleteAsync('../gulp-rename/dist', { force: true, dryRun: true });
console.log('would delete:', paths);
}
export function nodeClean() {
return rm('dist', { recursive: true, force: true });
}
The deleteAsync function takes a glob or an array of globs and
returns a promise with the list of the deleted paths; a task that returns the promise is finished when the
deletion is. We start with the problem.
Stale files
We build the project, rename b.txt to c.txt and build again. The
dist directory now has the file of the new name, but also the old one, which has no
source.
$ npx gulp build --silent $ ls dist a.txt b.txt $ mv src/b.txt src/c.txt $ npx gulp build --silent $ ls dist a.txt b.txt c.txt
The clean task
The clean task deletes the dist directory with all its content. When the
directory does not exist, the task does nothing and does not fail. The rebuild task
runs clean and then build, as the series function composes
them.
export function clean() {
return deleteAsync('dist');
}
export const rebuild = series(clean, build);
After the rebuild the directory holds only the files that have a source.
$ npx gulp rebuild [13:31:30] Using gulpfile ~/Documents/prog/js/gulp-clean/gulpfile.mjs [13:31:30] Starting 'rebuild'... [13:31:30] Starting 'clean'... [13:31:30] Finished 'clean' after 9.85 ms [13:31:30] Starting 'build'... [13:31:30] Finished 'build' after 10 ms [13:31:30] Finished 'rebuild' after 22 ms $ ls dist a.txt c.txt
Previewing a deletion
Before we run a pattern that we are not sure about, we can use the dryRun
option. The function then deletes nothing and returns the list of paths that would be deleted. The pattern
dist/** matches the directory itself and everything in it, so we exclude the directory
with a negative pattern; we want to empty it, not remove it. We add a keep.txt file first.
const paths = await deleteAsync(['dist/**', '!dist'], { dryRun: true });
console.log('would delete:', paths);
The task prints three absolute paths, and the files are still there.
$ touch dist/keep.txt $ npx gulp preview [13:31:31] Using gulpfile ~/Documents/prog/js/gulp-clean/gulpfile.mjs [13:31:31] Starting 'preview'... would delete: [ '~/Documents/prog/js/gulp-clean/dist/a.txt', '~/Documents/prog/js/gulp-clean/dist/c.txt', '~/Documents/prog/js/gulp-clean/dist/keep.txt' ] [13:31:31] Finished 'preview' after 9.69 ms $ ls dist a.txt c.txt keep.txt
Keeping files
More negative patterns keep selected files. The keep task empties
dist, except for keep.txt; this is useful for a directory that holds files
which the build does not produce, such as a deployed configuration.
const paths = await deleteAsync(['dist/**', '!dist', '!dist/keep.txt']);
console.log('deleted:', paths);
Only the two files that the build created are deleted.
$ npx gulp keep [13:31:31] Using gulpfile ~/Documents/prog/js/gulp-clean/gulpfile.mjs [13:31:31] Starting 'keep'... deleted: [ '~/Documents/prog/js/gulp-clean/dist/a.txt', '~/Documents/prog/js/gulp-clean/dist/c.txt' ] [13:31:31] Finished 'keep' after 11 ms $ ls dist keep.txt
The safety check
The del package refuses to delete files outside of the current working
directory, so a wrong path such as ../something cannot remove a sibling project. The
task fails with an error and a non-zero exit status.
await deleteAsync('../gulp-rename/dist');
The error message names the force option, which disables the check. We combine it
with dryRun and see what would be deleted.
$ npx gulp outside 2>&1 | head -4 [13:31:31] Using gulpfile ~/Documents/prog/js/gulp-clean/gulpfile.mjs [13:31:31] Starting 'outside'... [13:31:31] 'outside' errored after 7.77 ms [13:31:31] PresentableError: Cannot delete files/directories outside the current working directory. Can be overridden with the `force` option. $ npx gulp forced [13:31:32] Using gulpfile ~/Documents/prog/js/gulp-clean/gulpfile.mjs [13:31:32] Starting 'forced'... would delete: [ '~/Documents/prog/js/gulp-rename/dist' ] [13:31:32] Finished 'forced' after 8.48 ms
Without a dependency
Since Node.js 14.14 the fs.rm function can delete a directory recursively,
so a simple clean task needs no package. With the force option the function ignores
a missing path. The disadvantage is that it takes no globs, so it cannot keep any files.
import { rm } from 'node:fs/promises';
export function nodeClean() {
return rm('dist', { recursive: true, force: true });
}
The task removes the directory and ends successfully, even when we run it for the second time.
$ npx gulp nodeClean --silent $ ls dist ls: cannot access 'dist': No such file or directory $ npx gulp nodeClean --silent
Source
del on GitHub, Node.js fsPromises.rm, Gulp creating tasks
In this article we have cleaned the output of a Gulp 5 build: we saw how stale files appear, deleted
the directory in front of the build with series, previewed and limited the deletion, and met
the safety check of del and the fs.rm alternative. See also the Gulp series and parallel and Gulp src and dest tutorials.
Author
List all Gulp tutorials.