ZetCode

Gulp zip and deploy

last modified November 15, 2026

In this article we package and publish the result of a Gulp 5 build. We create a versioned ZIP archive with gulp-zip and copy the build to a server with rsync, started from a task.

Packaging and deployment

A build ends with files in a directory, but they must get to users. There are two common ways: an archive, which is attached to a release or uploaded by hand, and a synchronisation of the directory with a web server. Both are naturally the last steps of a pipeline, after the tasks described in the Gulp clean and Gulp series and parallel tutorials.

For the upload we do not use a Gulp plugin. The SFTP plugins, such as gulp-sftp-up4, are rarely updated, and they transfer all files each time. The rsync program is installed on most systems, sends only the changes over SSH, and can delete the files that are no longer in the build; a task can start it with spawn from node:child_process.

Installing the project

We create an ES module project and install Gulp, gulp-zip and del. The rsync command must be available on the machine.

$ mkdir gulp-zip
$ cd gulp-zip
$ npm init -y
$ npm pkg set type=module
$ npm i -D gulp gulp-zip del
$ mkdir -p src/css

The example project

The project has a page, a stylesheet and a PNG image in src. The build only copies them to dist, because the transformations are the subject of other tutorials, and the interesting part is what happens after the build.

src/index.html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Deploy demo</title>
<link rel="stylesheet" href="css/style.css">
</head>
<body>
<h1>Deploy demo</h1>
</body>
</html>
src/css/style.css
body { font-family: sans-serif; }

The gulpfile

The gulpfile reads the name and the version from package.json for the name of the archive, and the target of the deployment from the environment variable DEPLOY_TARGET; the default is a local directory, so that the example can be tried without a server.

gulpfile.mjs
import { src, dest, series } from 'gulp';
import { deleteAsync } from 'del';
import zip from 'gulp-zip';
import { spawn } from 'node:child_process';
import { readFileSync } from 'node:fs';

const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
const target = process.env.DEPLOY_TARGET || 'deploy-target/';

export function clean() {

    return deleteAsync(['dist', 'release']);
}

export function build() {

    return src('src/**/*', { encoding: false })
        .pipe(dest('dist'));
}

export function pack() {

    return src('dist/**/*', { encoding: false })
        .pipe(zip(`${pkg.name}-${pkg.version}.zip`))
        .pipe(dest('release'));
}

export function deploy(done) {

    const args = ['-az', '--delete', '--itemize-changes', 'dist/', target];
    const rsync = spawn('rsync', args, { stdio: 'inherit' });

    rsync.on('error', done);
    rsync.on('close', code => {
        done(code === 0 ? null : new Error(`rsync exited with code ${code}`));
    });
}

export const release = series(clean, build, pack);
export default series(clean, build, deploy);

The release task builds the project and creates the archive, and the default task builds it and deploys it.

Creating a ZIP archive

The zip() function turns the stream of files into one file with the given name; it is written with dest. The encoding: false option of src is necessary, because Gulp 5 would otherwise decode the images as UTF-8 text and damage them, see Gulp 5. The name contains the version, so that every release has its own archive. The paths in the archive are relative to the base of the glob, which is dist.

export function pack() {

    return src('dist/**/*', { encoding: false })
        .pipe(zip(`${pkg.name}-${pkg.version}.zip`))
        .pipe(dest('release'));
}

We run the task and list the archive. Then we extract the image and compare it with the original.

$ npx gulp release --silent
$ unzip -l release/gulp-zip-1.0.0.zip
Archive:  release/gulp-zip-1.0.0.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  2026-11-15 13:56   css/
      177  2026-11-15 13:55   index.html
     3008  2026-11-15 13:55   logo.png
       34  2026-11-15 13:55   css/style.css
---------                     -------
     3219                     4 files
$ mkdir /tmp/unzipped && unzip -q release/gulp-zip-1.0.0.zip -d /tmp/unzipped
$ cmp /tmp/unzipped/logo.png src/logo.png && echo "image is identical"
image is identical
$ rm -r /tmp/unzipped

Options of gulp-zip

The second parameter of zip() is an options object. The compress option (default true) turns compression off, and modifiedTime sets the same modification date for all entries. Archives of the same content then differ only if the content differs, which is useful when we compare releases or want reproducible builds.

.pipe(zip('site.zip', { modifiedTime: new Date('2026-01-01T00:00:00Z') }))

The date applies to the entries in the archive, not to the archive file itself.

Deploying with rsync

The deploy task starts rsync and passes its exit code to Gulp. The options are -a (archive: keeps permissions and times and recurses), -z (compression during the transfer), --delete (removes files from the target that are not in the source) and --itemize-changes (prints one line per change). The trailing slash in dist/ is important: it copies the contents of the directory, not the directory itself. An error event (rsync is not installed) and a non-zero exit code are both reported to the callback done, so the task fails and gulp exits with a non-zero status.

export function deploy(done) {

    const args = ['-az', '--delete', '--itemize-changes', 'dist/', target];
    const rsync = spawn('rsync', args, { stdio: 'inherit' });

    rsync.on('error', done);
    rsync.on('close', code => {
        done(code === 0 ? null : new Error(`rsync exited with code ${code}`));
    });
}

We run the default task, which cleans, builds and deploys to deploy-target/. The first run copies all files.

$ npx gulp
[13:56:06] Using gulpfile ~/Documents/prog/js/gulp-zip/gulpfile.mjs
[13:56:06] Starting 'default'...
[13:56:06] Starting 'clean'...
[13:56:06] Finished 'clean' after 11 ms
[13:56:06] Starting 'build'...
[13:56:06] Finished 'build' after 11 ms
[13:56:06] Starting 'deploy'...
created directory deploy-target
cd+++++++++ ./
>f+++++++++ index.html
>f+++++++++ logo.png
cd+++++++++ css/
>f+++++++++ css/style.css
[13:56:06] Finished 'deploy' after 49 ms
[13:56:06] Finished 'default' after 74 ms
$ ls -R deploy-target
deploy-target:
css
index.html
logo.png

deploy-target/css:
style.css

Incremental uploads and deleted files

A second run transfers no files, because rsync compares size and time of the files; the lines in the output are only the directories, whose times were reset by the clean task. After we remove the stylesheet and its reference from the sources, the next run uploads the changed page and deletes the old stylesheet from the target, thanks to --delete. Be careful with this option: a wrong target removes files that have nothing to do with the build.

$ npx gulp --silent
.d..t...... ./
.d..t...... css/
$ sed -i "/stylesheet/d" src/index.html && rm -r src/css
$ npx gulp --silent
*deleting   css/style.css
*deleting   css/
>f.st...... index.html
$ ls -R deploy-target
deploy-target:
index.html
logo.png

Deploying to a server

For a real server we set the target to the user@host:path/ form, with a key-based SSH login, so that the task does not wait for a password. If the transfer fails, the task fails, prints the message of rsync and exits with status 1, so a script or a CI job stops.

DEPLOY_TARGET=user@example.com:/var/www/site/ npx gulp deploy

The same variable works with the default task. We did not use a real server here; the transfer was tested against a local directory only, and the error handling against an unresolvable host name, whose real result follows.

$ DEPLOY_TARGET=nobody@localhost.invalid:/x/ npx gulp deploy
[13:56:08] Using gulpfile ~/Documents/prog/js/gulp-zip/gulpfile.mjs
[13:56:08] Starting 'deploy'...
ssh: Could not resolve hostname localhost.invalid: Name or service not known
rsync: connection unexpectedly closed (0 bytes received so far) [sender]
rsync error: unexplained error (code 255) at io.c(232) [sender=3.2.7]
[13:56:08] 'deploy' errored after 10 ms
[13:56:08] Error: rsync exited with code 255

Source

gulp-zip on npm, rsync manual page, Node.js child_process

In this article we have packaged a Gulp 5 build into a versioned ZIP archive with gulp-zip, and deployed it with rsync started from a task, including the failure handling. See also the Gulp src and dest and Gulp conditional pipelines 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.