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