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