1 | # @microsoft/gulp-core-build
|
2 |
|
3 | `gulp-core-build` is a set of utility functions that makes it easy to create gulp-based build rigs. Instead of having unweildy unmaintainable gulpfiles in every project, we want the build setup to be as reusable and centralized as possible.
|
4 |
|
5 | [![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build.svg)](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build)
|
6 | [![Build Status](https://travis-ci.org/Microsoft/gulp-core-build.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build) [![Dependencies](https://david-dm.org/Microsoft/gulp-core-build.svg)](https://david-dm.org/Microsoft/gulp-core-build)
|
7 |
|
8 | The gulp build system, along with its rich plugin ecosystem, is a very powerful tool for web development projects.
|
9 | However project gulp build setups become difficult to manage over time, as gulpfiles grow in complexity. This project
|
10 | simplifies a number of aspects of getting a build setup going for a majority of scenarios.
|
11 |
|
12 | Core build defines a contract for tasks to implement, such that they can share opinions about where things end up. Tasks are modular but they are designed to work well together.
|
13 |
|
14 | With gulp core build, your gulpfile translates into a list of task definitions, each which define what to run:
|
15 |
|
16 | ```typescript
|
17 | 'use strict';
|
18 |
|
19 | // Import core build and the tasks the project needs.
|
20 | let build = require('gulp-core-build');
|
21 | let lint = require('gulp-core-build-typescript').tslint;
|
22 | let typescript = require('gulp-core-build-typescript').typescript;
|
23 | let sass = require('gulp-core-build-sass').default;
|
24 | let webpack = require('gulp-core-build-webpack').default;
|
25 | let serve = require('gulp-core-build-serve').default;
|
26 |
|
27 | // Define gulp tasks.
|
28 | let buildTasks = build.task('build', build.parallel(lint, typescript, sass));
|
29 | let testTasks = build.task('test', build.serial(buildTasks, build.jest));
|
30 | let bundleTasks = build.task('bundle', build.serial(buildTasks, webpack));
|
31 | let serveTasks = build.task('serve', build.serial(bundleTasks, serve));
|
32 | let defaultTasks = build.task('default', testTasks);
|
33 |
|
34 | // Initialize!
|
35 | build.initialize(require('gulp'));
|
36 | ```
|
37 |
|
38 | # Usage
|
39 |
|
40 | Within your project, install gulp, gulp-core-build, and the tasks you need:
|
41 |
|
42 | ```
|
43 | npm install --save-dev gulp gulp-core-build
|
44 | ```
|
45 |
|
46 | Then install the tasks you need:
|
47 |
|
48 | ```
|
49 | npm install --save-dev gulp-core-build-typescript gulp-core-build-webpack gulp-core-build-serve
|
50 |
|
51 | ```
|
52 |
|
53 | Create a gulpfile.js that sets up the tasks in the way you want them to run:
|
54 |
|
55 | ```javascript
|
56 | 'use strict';
|
57 |
|
58 | // Import core build.
|
59 | let build = require('gulp-core-build');
|
60 |
|
61 | // Import the tasks.
|
62 | let lint = require('gulp-core-build-typescript').tslint;
|
63 | let typescript = require('gulp-core-build-typescript').typescript;
|
64 | let sass = require('gulp-core-build-sass').default;
|
65 | let webpack = require('gulp-core-build-webpack').default;
|
66 | let serve = require('gulp-core-build-serve').default;
|
67 |
|
68 | // Shorthand for defining custom subtasks
|
69 | // The proper method for this is to introduce a new package which exports a class that extends GulpTask
|
70 | // However, this shorthand allows an easy way to introduce one-off subtasks directly in the gulpfile
|
71 | let helloWorldSubtask = build.subTask('do-hello-world-subtask', function(gulp, buildOptions, done) {
|
72 | this.log('Hello, World!'); // use functions from GulpTask
|
73 | });
|
74 |
|
75 | // Define gulp tasks.
|
76 | let buildTasks = build.task('build', build.parallel(helloWorldSubtask, lint, typescript, sass));
|
77 | let testTasks = build.task('test', build.serial(buildTasks, build.jest));
|
78 | let bundleTasks = build.task('bundle', build.serial(buildTasks, webpack));
|
79 | let serveTasks = build.task('serve', build.serial(bundleTasks, serve));
|
80 | let helloWorldTasks = build.task('hello-world', helloWorldSubtask);
|
81 | let defaultTasks = build.task('default', testTasks);
|
82 |
|
83 | // Tell the build to set up gulp tasks with the given gulp instance.
|
84 | build.initialize(require('gulp'));
|
85 | ```
|
86 |
|
87 | Once this is set up, you should be able to execute the gulp tasks and they should run in the order you defined.
|
88 |
|
89 | # Available tasks
|
90 |
|
91 | | Task name | Description |
|
92 | | --------- | ----------- |
|
93 | | [gulp-core-build-typescript](https://www.npmjs.com/package/@microsoft/gulp-core-build-typescript) | Builds and lints typescript. |
|
94 | | [gulp-core-build-sass](https://www.npmjs.com/package/@microsoft/gulp-core-build) | Compiles sass into css, into js modules, that are theme friendly. |
|
95 | | [gulp-core-build-webpack](https://www.npmjs.com/package/@microsoft/gulp-core-build-webpack) | Runs webpack given a config, and outputs libraries plus the stats and logging. |
|
96 | | [gulp-core-build-serve](https://www.npmjs.com/package/@microsoft/gulp-core-build-serve) | Sets up a server and live reload for a quick dev loop. |
|
97 | | [gulp-core-build-mocha](https://www.npmjs.com/package/@microsoft/gulp-core-build-mocha) | Runs unit tests in a NodeJS environment with [Mocha](https://www.npmjs.com/package/mocha) |
|
98 |
|
99 | # API
|
100 |
|
101 | ## task(name, task)
|
102 |
|
103 | Defines a named task to be registered with gulp as a primary gulp task, which will run the provided task when execution.
|
104 |
|
105 | ## parallel(tasks)
|
106 |
|
107 | Runs a given list of tasks in parallel execution order.
|
108 |
|
109 | ## serial(tasks)
|
110 |
|
111 | Runs a given list of tasks in serial execution order.
|
112 |
|
113 | ## subtask(name: string, fn: ICustomGulpTask)
|
114 |
|
115 | Creates a subtask (which is not registered directly with gulp, use `task()` for that) which can be
|
116 | used with `parallel()` and `serial()`. The `this` variable in the callback function will be an instance of a `GulpTask`.
|
117 |
|
118 | `fn` should be a function of type `ICustomGulpTask`
|
119 |
|
120 | ```typescript
|
121 | /**
|
122 | * The callback interface for a custom task definition.
|
123 | * The task should either return a Promise, a stream, or call the
|
124 | * callback function (passing in an object value if there was an error).
|
125 | */
|
126 | export interface ICustomGulpTask {
|
127 | (gulp: gulp.Gulp | GulpProxy, buildConfig: IBuildConfig, done: (failure?: Object) => void):
|
128 | Promise<Object> | NodeJS.ReadWriteStream | void;
|
129 | }
|
130 | ```
|
131 |
|
132 | ## initialize(gulpInstance, [buildOtions])
|
133 |
|
134 | Registers the gulp tasks.
|
135 |
|
136 | The options are broken down into task-specific sections, and all are optional, so only provide the ones
|
137 | that require deviating from defaults:
|
138 |
|
139 | ```typescript
|
140 | build.initializeTasks(
|
141 | require('gulp'),
|
142 | {
|
143 | build: { /* build options */ },
|
144 | bundle: { /* bundle options */ },
|
145 | test: { /* test options */ },
|
146 | serve: { /* serve options */ },
|
147 | clean: { /* clean options */ }
|
148 | });
|
149 | ```
|
150 |
|
151 | ## addSuppression(suppression: string | RegExp)
|
152 |
|
153 | Suppresses a warning or an error message. It will no longer be displayed in the build logs, nor will the warning or error cause the build to fail.
|
154 |
|
155 | ```typescript
|
156 | // Suppresses this exact warning
|
157 | build.addSuppression("Warning - tslint /foo/bar/test.tsx no-any")
|
158 |
|
159 | // Suppresses anything with "tslint"
|
160 | build.addSuppression(/tslint/)
|
161 | ```
|
162 |
|
163 | # Building gulp-core-build
|
164 | 1. ```npm install --force```
|
165 | 2. ```gulp```
|
166 |
|
167 | # Defining a custom task
|
168 |
|
169 | The `subtask()` function is used to define a custom task. For example,
|
170 | you could create the following subtask, which is registered to the command
|
171 | `gulp hello-world`:
|
172 |
|
173 | ```javascript
|
174 | let helloWorldSubtask = build.subTask('do-hello-world-subtask', function(gulp, buildOptions, done) {
|
175 | this.log('Hello, World!'); // use functions from GulpTask
|
176 | });
|
177 |
|
178 | // Register the task with gulp command line
|
179 | let helloWorldTask = build.task('hello-world', helloWorldSubtask);
|
180 | ```
|
181 |
|
182 | Note that the command `gulp do-hello-world-subtask` would error.
|
183 |
|
184 |
|
185 | # License
|
186 |
|
187 | MIT
|