ZetCode

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.

gulpfile.mjs
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

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.