The streaming build system

What is gulp?

• Automation - gulp is a toolkit that helps you automate painful or time-consuming tasks in your development workflow.
• Platform-agnostic - Integrations are built into all major IDEs and people are using gulp with PHP, .NET, Node.js, Java, and other platforms.
• Strong Ecosystem - Use npm modules to do anything you want + over 2000 curated plugins for streaming file transformations
• Simple - By providing only a minimal API surface, gulp is easy to learn and simple to use

Installation

There are a few ways to install:

• gulp v4.0.0 - npm install gulp@next
• gulp v4.0.0-alpha.3 - npm install gulpjs/gulp#v4.0.0-alpha.3
• gulp v3.9.1 - npm install gulp

Documentation

For a Getting started guide, API docs, recipes, making a plugin, etc. check out our docs!

• Check out the documentation for v4.0.0! Excuse our dust; these docs might be behind while we get everything updated. Please open an issue if something isn't working.
• Using the older v3.9.1? Check out the documentation at the v3.9.1 tag!

Sample gulpfile.js

This file will give you a taste of what gulp does.

vargulp=require('gulp');varless=require('gulp-less');varbabel=require('gulp-babel');varconcat=require('gulp-concat');varuglify=require('gulp-uglify');varrename=require('gulp-rename');varcleanCSS=require('gulp-clean-css');vardel=require('del');varpaths={styles: {src: 'src/styles/**/*.less',dest: 'assets/styles/'},scripts: {src: 'src/scripts/**/*.js',dest: 'assets/scripts/'}};/* Not all tasks need to use streams, a gulpfile is just another node program * and you can use all packages available on npm, but it must return either a * Promise, a Stream or take a callback and call it */functionclean(){// You can use multiple globbing patterns as you would with `gulp.src`,// for example if you are using del 2.0 or above, return its promisereturndel(['assets']);}/* * Define our tasks using plain functions */functionstyles(){returngulp.src(paths.styles.src).pipe(less()).pipe(cleanCSS())// pass in options to the stream.pipe(rename({basename: 'main',suffix: '.min'})).pipe(gulp.dest(paths.styles.dest));}functionscripts(){returngulp.src(paths.scripts.src,{sourcemaps: true}).pipe(babel()).pipe(uglify()).pipe(concat('main.min.js')).pipe(gulp.dest(paths.scripts.dest));}functionwatch(){gulp.watch(paths.scripts.src,scripts);gulp.watch(paths.styles.src,styles);}/* * You can use CommonJS `exports` module notation to declare tasks */exports.clean=clean;exports.styles=styles;exports.scripts=scripts;exports.watch=watch;/* * Specify if tasks run in series or parallel using `gulp.series` and `gulp.parallel` */varbuild=gulp.series(clean,gulp.parallel(styles,scripts));/* * You can still use `gulp.task` to expose tasks */gulp.task('build',build);/* * Define default task that can be called by just running `gulp` from cli */gulp.task('default',build);

Use latest JavaScript version in your gulpfile

Node already supports a lot of ES2015, to avoid compatibility problem we suggest to install Babel and rename your gulpfile.js as gulpfile.babel.js.

npm install --save-dev babel-register babel-preset-es2015

Then create a .babelrc file with the preset configuration.

{"presets": ["es2015"]}

And here's the same sample from above written in ES2015.

importgulpfrom'gulp';importlessfrom'gulp-less';importbabelfrom'gulp-babel';importconcatfrom'gulp-concat';importuglifyfrom'gulp-uglify';importrenamefrom'gulp-rename';importcleanCSSfrom'gulp-clean-css';importdelfrom'del';constpaths={styles: {src: 'src/styles/**/*.less',dest: 'assets/styles/'},scripts: {src: 'src/scripts/**/*.js',dest: 'assets/scripts/'}};/* * For small tasks you can export arrow functions */exportconstclean=()=>del(['assets']);/* * You can also declare named functions and export them as tasks */exportfunctionstyles(){returngulp.src(paths.styles.src).pipe(less()).pipe(cleanCSS())// pass in options to the stream.pipe(rename({basename: 'main',suffix: '.min'})).pipe(gulp.dest(paths.styles.dest));}exportfunctionscripts(){returngulp.src(paths.scripts.src,{sourcemaps: true}).pipe(babel()).pipe(uglify()).pipe(concat('main.min.js')).pipe(gulp.dest(paths.scripts.dest));}/* * You could even use `export as` to rename exported tasks */functionwatchFiles(){gulp.watch(paths.scripts.src,scripts);gulp.watch(paths.styles.src,styles);}export{watchFilesaswatch};/* * You can still use `gulp.task` * for example to set task names that would otherwise be invalid */constbuild=gulp.series(clean,gulp.parallel(styles,scripts));gulp.task('build',build);/* * Export a default task */exportdefaultbuild;

Incremental Builds

You can filter out unchanged files between runs of a task using the gulp.src function's since option and gulp.lastRun:

constpaths={
...
images: {src: 'src/images/**/*.{jpg,jpeg,png}',dest: 'build/img/'}}functionimages(){returngulp.src(paths.images.src,{since: gulp.lastRun(images)}).pipe(imagemin({optimizationLevel: 5})).pipe(gulp.dest(paths.images.dest));}functionwatch(){gulp.watch(paths.images.src,images);}

Task run times are saved in memory and are lost when gulp exits. It will only save time during the watch task when running the images task for a second time.

If you want to compare modification time between files instead, we recommend these plugins:

• gulp-changed;
• or gulp-newer - supports many:1 source:dest.

gulp-newer example:

functionimages(){vardest='build/img';returngulp.src(paths.images).pipe(newer(dest))// pass through newer images only.pipe(imagemin({optimizationLevel: 5})).pipe(gulp.dest(dest));}

If you can't simply filter out unchanged files, but need them in a later phase of the stream, we recommend these plugins:

• gulp-cached - in-memory file cache, not for operation on sets of files
• gulp-remember - pairs nicely with gulp-cached

gulp-remember example:

functionscripts(){returngulp.src(scriptsGlob).pipe(cache('scripts'))// only pass through changed files.pipe(header('(function () {'))// do special things to the changed files....pipe(footer('})();'))// for example,// add a simple module wrap to each file.pipe(remember('scripts'))// add back all files to the stream.pipe(concat('app.js'))// do things that require all files.pipe(gulp.dest('public/'))}

Want to contribute?

Anyone can help make this project better - check out our Contributing guide!

Backers

Support us with a monthly donation and help us continue our activities.

Sponsors

Become a sponsor to get your logo on our README on Github.