ZetCode

Gulp concat

last modified November 15, 2026

In this article we join files with Gulp 5 and the gulp-concat plugin. We show why the order of the files matters, how to control it, how to add a separator, and how to combine concatenation with minification.

The gulp-concat plugin

Concatenation joins many files into one. A page that loads one script instead of ten makes fewer requests, and a single file is easier to minify and cache. Modern bundlers do more, but for classic scripts and stylesheets a task runner is enough. The gulp-concat plugin collects all the files that pass through the stream and emits a single file with the given name. The plugin works for any text files, so we can use it for scripts and for stylesheets.

Installing the project

We create a project and install Gulp, gulp-concat and gulp-terser, which we use to minify the bundle.

$ mkdir gulp-concat
$ cd gulp-concat
$ npm init -y
$ npm i -D gulp gulp-concat gulp-terser
$ mkdir -p src/js src/css

The example project

The project has three scripts in the src/js directory. The first one defines a helper function.

src/js/utils.js
function formatPrice(value) {
    return value.toFixed(2) + ' EUR';
}

The formatPrice function formats a number as a price in euros. The second script defines a class that uses the function.

src/js/models.js
class Product {

    constructor(name, price) {
        this.name = name;
        this.price = price;
    }

    toString() {
        return `${this.name}: ${formatPrice(this.price)}`;
    }
}

The Product class has a name and a price, and its toString method calls formatPrice. The third script is the entry point; it creates a product and prints it.

src/js/app.js
const product = new Product('Keyboard', 49.9);
console.log(product.toString());

The script uses the class at the top level, so the class must be defined before this file runs. The two stylesheets in src/css are tiny; we use them in the last section.

gulpfile.mjs
import { src, dest } from 'gulp';
import concat from 'gulp-concat';
import terser from 'gulp-terser';

export function alphabetical() {

    return src('src/js/*.js')
        .pipe(concat('bundle.js'))
        .pipe(dest('dist/alphabetical'));
}

const scripts = ['src/js/utils.js', 'src/js/models.js', 'src/js/app.js'];

export function ordered() {

    return src(scripts)
        .pipe(concat('bundle.js'))
        .pipe(dest('dist/ordered'));
}

export function minified() {

    return src(scripts)
        .pipe(concat('bundle.min.js'))
        .pipe(terser())
        .pipe(dest('dist/minified'));
}

export function separator() {

    return src(scripts)
        .pipe(concat('bundle.js', { newLine: '\n/* ---- */\n' }))
        .pipe(dest('dist/separator'));
}

export function styles() {

    return src(['src/css/base.css', 'src/css/theme.css'])
        .pipe(concat('all.css'))
        .pipe(dest('dist/css'));
}

The gulpfile has a task for every way of joining the files. We examine them one by one.

The order of the files

The alphabetical task passes the glob src/js/*.js. The glob returns the files in alphabetical order, so app.js comes first, and the bundle uses Product before it is defined. A class declaration is not hoisted like a function, so running the bundle fails. A bug like this is easy to introduce when a project grows, and the error shows up only in the browser or when the bundle is run.

$ npx gulp alphabetical --silent
$ node dist/alphabetical/bundle.js 2>&1 | head -5
~/Documents/prog/js/gulp-concat/dist/alphabetical/bundle.js:1
const product = new Product('Keyboard', 49.9);
                ^

ReferenceError: Cannot access 'Product' before initialization

The fix is to list the files explicitly. When src receives an array, the files are emitted in the order of the array; the stream keeps the order of the globs.

const scripts = ['src/js/utils.js', 'src/js/models.js', 'src/js/app.js'];

return src(scripts)
    .pipe(concat('bundle.js'))
    .pipe(dest('dist/ordered'));

The bundle now has the dependencies first, and the script runs and prints the product.

$ npx gulp ordered --silent
$ cat dist/ordered/bundle.js
function formatPrice(value) {
    return value.toFixed(2) + ' EUR';
}

class Product {

    constructor(name, price) {
        this.name = name;
        this.price = price;
    }

    toString() {
        return `${this.name}: ${formatPrice(this.price)}`;
    }
}

const product = new Product('Keyboard', 49.9);
console.log(product.toString());
$ node dist/ordered/bundle.js
Keyboard: 49.90 EUR

Joining with minification

Concatenation is usually followed by minification. We put terser after concat, so Terser minifies the bundle once instead of each file separately. The empty lines between the files disappear and the whole bundle becomes a single line.

return src(scripts)
    .pipe(concat('bundle.min.js'))
    .pipe(terser())
    .pipe(dest('dist/minified'));

The minified bundle behaves like the original; it prints the same text.

$ npx gulp minified --silent
$ cat dist/minified/bundle.min.js
function formatPrice(t){return t.toFixed(2)+" EUR"}class Product{constructor(t,r){this.name=t,this.price=r}toString(){return`${this.name}: ${formatPrice(this.price)}`}}const product=new Product("Keyboard",49.9);console.log(product.toString());
$ node dist/minified/bundle.min.js
Keyboard: 49.90 EUR

The newLine option

The plugin joins the files with a line feed. The newLine option changes the separator. This is needed for scripts that do not end with a semicolon, where a separator of ';' prevents the last statement of a file from merging with the first one of the next file. It can also mark the boundaries between the files, as in this example.

concat('bundle.js', { newLine: '\n/* ---- */\n' })

The separator appears between the files, but not after the last one.

$ npx gulp separator --silent
$ cat dist/separator/bundle.js
function formatPrice(value) {
    return value.toFixed(2) + ' EUR';
}

/* ---- */
class Product {

    constructor(name, price) {
        this.name = name;
        this.price = price;
    }

    toString() {
        return `${this.name}: ${formatPrice(this.price)}`;
    }
}

/* ---- */
const product = new Product('Keyboard', 49.9);
console.log(product.toString());

Concatenating stylesheets

The plugin knows nothing about the content, so it works for CSS in the same way. The order is again significant: later rules override the earlier ones with the same specificity, so the theme must follow the base styles.

return src(['src/css/base.css', 'src/css/theme.css'])
    .pipe(concat('all.css'))
    .pipe(dest('dist/css'));

The result contains both files. Joined stylesheets can be minified with clean-css or cssnano. One more thing: a CSS @import inside a concatenated file is not allowed after other rules, so the imports must be resolved before the files are joined.

$ npx gulp styles --silent
$ cat dist/css/all.css
body { margin: 0; }

body { color: #333; }

Source

gulp-concat on npm, Gulp src

In this article we have joined files with gulp-concat in Gulp 5: we controlled the order of the files, combined concatenation with Terser, changed the separator, and joined stylesheets. See also the Gulp Terser and Gulp source maps 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.