1 | <p align="center">
|
2 | <a href="https://gulpjs.com">
|
3 | <img height="257" width="114" src="https://raw.githubusercontent.com/gulpjs/artwork/master/gulp-2x.png">
|
4 | </a>
|
5 | <p align="center">The streaming build system</p>
|
6 | </p>
|
7 |
|
8 | [![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Azure Pipelines Build Status][azure-pipelines-image]][azure-pipelines-url] [![Build Status][travis-image]][travis-url] [![AppVeyor Build Status][appveyor-image]][appveyor-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![OpenCollective Backers][backer-badge]][backer-url] [![OpenCollective Sponsors][sponsor-badge]][sponsor-url] [![Gitter chat][gitter-image]][gitter-url]
|
9 |
|
10 |
|
11 | ## What is gulp?
|
12 |
|
13 | - **Automation** - gulp is a toolkit that helps you automate painful or time-consuming tasks in your development workflow.
|
14 | - **Platform-agnostic** - Integrations are built into all major IDEs and people are using gulp with PHP, .NET, Node.js, Java, and other platforms.
|
15 | - **Strong Ecosystem** - Use npm modules to do anything you want + over 2000 curated plugins for streaming file transformations
|
16 | - **Simple** - By providing only a minimal API surface, gulp is easy to learn and simple to use
|
17 |
|
18 | ## What's new in 4.0?!
|
19 |
|
20 | * The task system was rewritten from the ground-up, allowing task composition using `series()` and `parallel()` methods
|
21 | * The watcher was updated, now using chokidar (no more need for gulp-watch!), with feature parity to our task system
|
22 | * First-class support was added for incremental builds using `lastRun()`
|
23 | * A `symlink()` method was exposed to create symlinks instead of copying files
|
24 | * Built-in support for sourcemaps was added - the gulp-sourcemaps plugin is no longer necessary!
|
25 | * Task registration of exported functions - using node or ES exports - is now recommended
|
26 | * Custom registries were designed, allowing for shared tasks or augmented functionality
|
27 | * Stream implementations were improved, allowing for better conditional and phased builds
|
28 |
|
29 | ## Installation
|
30 |
|
31 | Follow our [Quick Start guide][quick-start].
|
32 |
|
33 | ## Roadmap
|
34 |
|
35 | Find out about all our work-in-progress and outstanding issues at https://github.com/orgs/gulpjs/projects.
|
36 |
|
37 | ## Documentation
|
38 |
|
39 | Check out the [Getting Started guide][getting-started-guide] and [API docs][api-docs] on our website!
|
40 |
|
41 | __Excuse our dust! All other docs will be behind until we get everything updated. Please open an issue if something isn't working.__
|
42 |
|
43 | ## Sample `gulpfile.js`
|
44 |
|
45 | This file will give you a taste of what gulp does.
|
46 |
|
47 | ```js
|
48 | var gulp = require('gulp');
|
49 | var less = require('gulp-less');
|
50 | var babel = require('gulp-babel');
|
51 | var concat = require('gulp-concat');
|
52 | var uglify = require('gulp-uglify');
|
53 | var rename = require('gulp-rename');
|
54 | var cleanCSS = require('gulp-clean-css');
|
55 | var del = require('del');
|
56 |
|
57 | var paths = {
|
58 | styles: {
|
59 | src: 'src/styles/**/*.less',
|
60 | dest: 'assets/styles/'
|
61 | },
|
62 | scripts: {
|
63 | src: 'src/scripts/**/*.js',
|
64 | dest: 'assets/scripts/'
|
65 | }
|
66 | };
|
67 |
|
68 | /* Not all tasks need to use streams, a gulpfile is just another node program
|
69 | * and you can use all packages available on npm, but it must return either a
|
70 | * Promise, a Stream or take a callback and call it
|
71 | */
|
72 | function clean() {
|
73 | // You can use multiple globbing patterns as you would with `gulp.src`,
|
74 | // for example if you are using del 2.0 or above, return its promise
|
75 | return del([ 'assets' ]);
|
76 | }
|
77 |
|
78 | /*
|
79 | * Define our tasks using plain functions
|
80 | */
|
81 | function styles() {
|
82 | return gulp.src(paths.styles.src)
|
83 | .pipe(less())
|
84 | .pipe(cleanCSS())
|
85 | // pass in options to the stream
|
86 | .pipe(rename({
|
87 | basename: 'main',
|
88 | suffix: '.min'
|
89 | }))
|
90 | .pipe(gulp.dest(paths.styles.dest));
|
91 | }
|
92 |
|
93 | function scripts() {
|
94 | return gulp.src(paths.scripts.src, { sourcemaps: true })
|
95 | .pipe(babel())
|
96 | .pipe(uglify())
|
97 | .pipe(concat('main.min.js'))
|
98 | .pipe(gulp.dest(paths.scripts.dest));
|
99 | }
|
100 |
|
101 | function watch() {
|
102 | gulp.watch(paths.scripts.src, scripts);
|
103 | gulp.watch(paths.styles.src, styles);
|
104 | }
|
105 |
|
106 | /*
|
107 | * Specify if tasks run in series or parallel using `gulp.series` and `gulp.parallel`
|
108 | */
|
109 | var build = gulp.series(clean, gulp.parallel(styles, scripts));
|
110 |
|
111 | /*
|
112 | * You can use CommonJS `exports` module notation to declare tasks
|
113 | */
|
114 | exports.clean = clean;
|
115 | exports.styles = styles;
|
116 | exports.scripts = scripts;
|
117 | exports.watch = watch;
|
118 | exports.build = build;
|
119 | /*
|
120 | * Define default task that can be called by just running `gulp` from cli
|
121 | */
|
122 | exports.default = build;
|
123 | ```
|
124 |
|
125 | ## Use latest JavaScript version in your gulpfile
|
126 |
|
127 | __Most new versions of node support most features that Babel provides, except the `import`/`export` syntax. When only that syntax is desired, rename to `gulpfile.esm.js`, install the [esm][esm-module] module, and skip the Babel portion below.__
|
128 |
|
129 | Node already supports a lot of __ES2015+__ features, but to avoid compatibility problems we suggest to install Babel and rename your `gulpfile.js` to `gulpfile.babel.js`.
|
130 |
|
131 | ```sh
|
132 | npm install --save-dev @babel/register @babel/core @babel/preset-env
|
133 | ```
|
134 |
|
135 | Then create a **.babelrc** file with the preset configuration.
|
136 |
|
137 | ```js
|
138 | {
|
139 | "presets": [ "@babel/preset-env" ]
|
140 | }
|
141 | ```
|
142 |
|
143 | And here's the same sample from above written in **ES2015+**.
|
144 |
|
145 | ```js
|
146 | import gulp from 'gulp';
|
147 | import less from 'gulp-less';
|
148 | import babel from 'gulp-babel';
|
149 | import concat from 'gulp-concat';
|
150 | import uglify from 'gulp-uglify';
|
151 | import rename from 'gulp-rename';
|
152 | import cleanCSS from 'gulp-clean-css';
|
153 | import del from 'del';
|
154 |
|
155 | const paths = {
|
156 | styles: {
|
157 | src: 'src/styles/**/*.less',
|
158 | dest: 'assets/styles/'
|
159 | },
|
160 | scripts: {
|
161 | src: 'src/scripts/**/*.js',
|
162 | dest: 'assets/scripts/'
|
163 | }
|
164 | };
|
165 |
|
166 | /*
|
167 | * For small tasks you can export arrow functions
|
168 | */
|
169 | export const clean = () => del([ 'assets' ]);
|
170 |
|
171 | /*
|
172 | * You can also declare named functions and export them as tasks
|
173 | */
|
174 | export function styles() {
|
175 | return gulp.src(paths.styles.src)
|
176 | .pipe(less())
|
177 | .pipe(cleanCSS())
|
178 | // pass in options to the stream
|
179 | .pipe(rename({
|
180 | basename: 'main',
|
181 | suffix: '.min'
|
182 | }))
|
183 | .pipe(gulp.dest(paths.styles.dest));
|
184 | }
|
185 |
|
186 | export function scripts() {
|
187 | return gulp.src(paths.scripts.src, { sourcemaps: true })
|
188 | .pipe(babel())
|
189 | .pipe(uglify())
|
190 | .pipe(concat('main.min.js'))
|
191 | .pipe(gulp.dest(paths.scripts.dest));
|
192 | }
|
193 |
|
194 | /*
|
195 | * You could even use `export as` to rename exported tasks
|
196 | */
|
197 | function watchFiles() {
|
198 | gulp.watch(paths.scripts.src, scripts);
|
199 | gulp.watch(paths.styles.src, styles);
|
200 | }
|
201 | export { watchFiles as watch };
|
202 |
|
203 | const build = gulp.series(clean, gulp.parallel(styles, scripts));
|
204 | /*
|
205 | * Export a default task
|
206 | */
|
207 | export default build;
|
208 | ```
|
209 |
|
210 | ## Incremental Builds
|
211 |
|
212 | You can filter out unchanged files between runs of a task using
|
213 | the `gulp.src` function's `since` option and `gulp.lastRun`:
|
214 | ```js
|
215 | const paths = {
|
216 | ...
|
217 | images: {
|
218 | src: 'src/images/**/*.{jpg,jpeg,png}',
|
219 | dest: 'build/img/'
|
220 | }
|
221 | }
|
222 |
|
223 | function images() {
|
224 | return gulp.src(paths.images.src, {since: gulp.lastRun(images)})
|
225 | .pipe(imagemin({optimizationLevel: 5}))
|
226 | .pipe(gulp.dest(paths.images.dest));
|
227 | }
|
228 |
|
229 | function watch() {
|
230 | gulp.watch(paths.images.src, images);
|
231 | }
|
232 | ```
|
233 | Task run times are saved in memory and are lost when gulp exits. It will only
|
234 | save time during the `watch` task when running the `images` task
|
235 | for a second time.
|
236 |
|
237 | ## Want to contribute?
|
238 |
|
239 | Anyone can help make this project better - check out our [Contributing guide](/CONTRIBUTING.md)!
|
240 |
|
241 | ## Backers
|
242 |
|
243 | Support us with a monthly donation and help us continue our activities.
|
244 |
|
245 | [![Backers][backers-image]][support-url]
|
246 |
|
247 | ## Sponsors
|
248 |
|
249 | Become a sponsor to get your logo on our README on Github.
|
250 |
|
251 | [![Sponsors][sponsors-image]][support-url]
|
252 |
|
253 | [downloads-image]: https://img.shields.io/npm/dm/gulp.svg
|
254 | [npm-url]: https://www.npmjs.com/package/gulp
|
255 | [npm-image]: https://img.shields.io/npm/v/gulp.svg
|
256 |
|
257 | [azure-pipelines-url]: https://dev.azure.com/gulpjs/gulp/_build/latest?definitionId=1&branchName=master
|
258 | [azure-pipelines-image]: https://dev.azure.com/gulpjs/gulp/_apis/build/status/gulp?branchName=master
|
259 |
|
260 | [travis-url]: https://travis-ci.org/gulpjs/gulp
|
261 | [travis-image]: https://img.shields.io/travis/gulpjs/gulp.svg?label=travis-ci
|
262 |
|
263 | [appveyor-url]: https://ci.appveyor.com/project/gulpjs/gulp
|
264 | [appveyor-image]: https://img.shields.io/appveyor/ci/gulpjs/gulp.svg?label=appveyor
|
265 |
|
266 | [coveralls-url]: https://coveralls.io/r/gulpjs/gulp
|
267 | [coveralls-image]: https://img.shields.io/coveralls/gulpjs/gulp/master.svg
|
268 |
|
269 | [gitter-url]: https://gitter.im/gulpjs/gulp
|
270 | [gitter-image]: https://badges.gitter.im/gulpjs/gulp.svg
|
271 |
|
272 | [backer-url]: #backers
|
273 | [backer-badge]: https://opencollective.com/gulpjs/backers/badge.svg?color=blue
|
274 | [sponsor-url]: #sponsors
|
275 | [sponsor-badge]: https://opencollective.com/gulpjs/sponsors/badge.svg?color=blue
|
276 |
|
277 | [support-url]: https://opencollective.com/gulpjs#support
|
278 |
|
279 | [backers-image]: https://opencollective.com/gulpjs/backers.svg
|
280 | [sponsors-image]: https://opencollective.com/gulpjs/sponsors.svg
|
281 |
|
282 | [quick-start]: https://gulpjs.com/docs/en/getting-started/quick-start
|
283 | [getting-started-guide]: https://gulpjs.com/docs/en/getting-started/quick-start
|
284 | [api-docs]: https://gulpjs.com/docs/en/api/concepts
|