Skip to content

Commit 24e4efc

Browse files
author
nickpape-msft
committed
Improve README
1 parent 7438f48 commit 24e4efc

8 files changed

Lines changed: 470 additions & 119 deletions

File tree

‎BUILDING.md‎

Whitespace-only changes.

‎README.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# gulp-core-build [![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build.svg)](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build)
2+
3+
[![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)
4+
5+
The gulp build system, along with its rich plugin ecosystem, is a very powerful tool for web development projects.
6+
However, project gulp build setups become difficult to manage over time, as gulpfiles grow in complexity. This project
7+
simplifies a number of aspects of getting a build setup going for a majority of scenarios.
8+
9+
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.
10+
11+
With gulp core build, your gulpfile translates into a list of task definitions, each which define what to run:
12+
13+
```typescript
14+
'use strict';
15+
16+
// Import core build and the tasks the project needs.
17+
let build = require('gulp-core-build');
18+
let lint = require('gulp-core-build-typescript').tslint;
19+
let typescript = require('gulp-core-build-typescript').typescript;
20+
let sass = require('gulp-core-build-sass').default;
21+
let karma = require('gulp-core-build-karma').default;
22+
let webpack = require('gulp-core-build-webpack').default;
23+
let serve = require('gulp-core-build-serve').default;
24+
25+
// Define gulp tasks.
26+
let buildTasks = build.task('build', build.parallel(lint, typescript, sass));
27+
let testTasks = build.task('test', build.serial(buildTasks, karma));
28+
let bundleTasks = build.task('bundle', build.serial(buildTasks, webpack));
29+
let serveTasks = build.task('serve', build.serial(bundleTasks, serve));
30+
let defaultTasks = build.task('default', testTasks);
31+
32+
// Initialize!
33+
build.initialize(require('gulp'));
34+
```
35+
36+
# Usage
37+
38+
Within your project, install gulp, gulp-core-build, and the tasks you need:
39+
40+
```
41+
npm install --save-dev gulp gulp-core-build
42+
```
43+
44+
Then install the tasks you need:
45+
46+
```
47+
npm install --save-dev gulp-core-build-typescript gulp-core-build-karma gulp-core-build-webpack gulp-core-build-serve
48+
49+
```
50+
51+
Create a gulpfile.js that sets up the tasks in the way you want them to run:
52+
53+
```javascript
54+
'use strict';
55+
56+
// Import core build.
57+
let build = require('gulp-core-build');
58+
59+
// Import the tasks.
60+
let lint = require('gulp-core-build-typescript').tslint;
61+
let typescript = require('gulp-core-build-typescript').typescript;
62+
let sass = require('gulp-core-build-sass').default;
63+
let karma = require('gulp-core-build-karma').default;
64+
let webpack = require('gulp-core-build-webpack').default;
65+
let serve = require('gulp-core-build-serve').default;
66+
67+
// Shorthand for defining custom subtasks
68+
// The proper method for this is to introduce a new package which exports a class that extends GulpTask
69+
// However, this shorthand allows an easy way to introduce one-off subtasks directly in the gulpfile
70+
let helloWorldSubtask = build.subTask('do-hello-world-subtask', function(gulp, buildOptions, done) {
71+
this.log('Hello, World!'); // use functions from GulpTask
72+
});
73+
74+
// Define gulp tasks.
75+
let buildTasks = build.task('build', build.parallel(helloWorldSubtask, lint, typescript, sass));
76+
let testTasks = build.task('test', build.serial(buildTasks, karma));
77+
let bundleTasks = build.task('bundle', build.serial(buildTasks, webpack));
78+
let serveTasks = build.task('serve', build.serial(bundleTasks, serve));
79+
let helloWorldTasks = build.task('hello-world', helloWorldSubtask);
80+
let defaultTasks = build.task('default', testTasks);
81+
82+
// Tell the build to set up gulp tasks with the given gulp instance.
83+
build.initialize(require('gulp'));
84+
```
85+
86+
Once this is set up, you should be able to execute the gulp tasks and they should run in the order you defined.
87+
88+
# Available tasks
89+
90+
| Task name | Description |
91+
| --------- | ----------- |
92+
| [gulp-core-build-typescript](https://www.npmjs.com/package/@microsoft/gulp-core-build-typescript) | Builds and lints typescript. |
93+
| [gulp-core-build-sass](https://www.npmjs.com/package/@microsoft/gulp-core-build) | Compiles sass into css, into js modules, that are theme friendly. |
94+
| [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. |
95+
| [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. |
96+
| [gulp-core-build-karma](https://www.npmjs.com/package/@microsoft/gulp-core-build-karma) | Runs unit tests in a browser using [Karma](https://www.npmjs.com/package/karma) |
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+
| [sp-build-core-tasks](https://www.npmjs.com/package/@microsoft/sp-build-core-tasks) | Special tasks for developing with the SharePoint Framework (SPFx) |
99+
100+
# API
101+
102+
## task(name, task)
103+
104+
Defines a named task to be registered with gulp as a primary gulp task, which will run the provided task when execution.
105+
106+
## parallel(tasks)
107+
108+
Runs a given list of tasks in parallel execution order.
109+
110+
## serial(tasks)
111+
112+
Runs a given list of tasks in serial execution order.
113+
114+
## subtask(name, fn)
115+
116+
Creates a subtask (which is not registered directly with gulp, use `task()` for that) which can be
117+
used with parallel and serial. The `this` variable in the callback function will be an instance of a `GulpTask`.
118+
119+
`fn` should be a function which accepts 3 parameters: a `gulp` instance, the build configuration
120+
object, and an optional callback function to signify subtask completion.
121+
122+
## initialize(gulpInstance, [buildOtions])
123+
124+
Registers the gulp tasks.
125+
126+
The options are broken down into task-specific sections, and all are optional, so only provide the ones
127+
that require deviating from defaults:
128+
129+
```typescript
130+
build.initializeTasks(
131+
require('gulp'),
132+
{
133+
build: { /* build options */ },
134+
bundle: { /* bundle options */ },
135+
test: { /* test options */ },
136+
serve: { /* serve options */ },
137+
nuke: { /* nuke options */ }
138+
});
139+
```
140+
# Building gulp-core-build
141+
1. ```npm install --force```
142+
2. ```gulp```
143+
144+
# Defining a custom task
145+
146+
The `subtask()` function is used to define a custom task. For example,
147+
you could create the following subtask, which is registered to the command
148+
`gulp hello-world`:
149+
150+
```javascript
151+
let helloWorldSubtask = build.subTask('do-hello-world-subtask', function(gulp, buildOptions, done) {
152+
this.log('Hello, World!'); // use functions from GulpTask
153+
});
154+
155+
// Register the task with gulp command line
156+
let helloWorldTask = build.task('hello-world', helloWorldSubtask);
157+
```
158+
159+
Note that the command `gulp do-hello-world-subtask` would error.
160+
161+
162+
# License
163+
164+
MIT

‎gulp-core-build-karma/README.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,42 @@
1+
A gulp-core-build plugin which uses KarmaJS to run unit tests.
2+
13
# gulp-core-build-karma [![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-karma.svg)](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-karma)
24

35
[![Build Status](https://travis-ci.org/Microsoft/gulp-core-build-karma.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build-karma) [![Dependencies](https://david-dm.org/Microsoft/gulp-core-build-karma.svg)](https://david-dm.org/Microsoft/gulp-core-build-karma)
6+
7+
# Description
8+
9+
**gulp-core-build-karma** is a gulp-core-build plugin which uses KarmaJS to configure a browser
10+
to run a bundle of code, primarily unit tests using mocha.
11+
12+
# KarmaTask
13+
## Usage
14+
15+
Simply register the task in a gulp-core-build tree, and it will automatically look for a **karma.config.js** file.
16+
The default karma config, which can be obtained by running the task with the `--initkarma` flag,
17+
always looks for a file called `src/tests.js` and uses this as the entry point for the bundle which will
18+
be tested.
19+
20+
The task will launch the PhantomJS browser and begin automatically running mocha tests.
21+
22+
Once testing is complete, a coverage report is written to the `coverage` folder.
23+
24+
A number of plugins for karma are automatically configured, including:
25+
* karma-webpack
26+
* karma-mocha
27+
* karma-coverage
28+
* karma-phantomjs-launcher
29+
* karma-sinon-chai
30+
31+
## Configuration
32+
33+
### karmaConfigPath
34+
35+
Sets the path to the Karma Configuration file to use. If one has not been created, this task
36+
will prompt the user to run it again with the `--initkarma` flag.
37+
38+
**Default:** './karma.config.json'
39+
40+
# License
41+
42+
MIT

‎gulp-core-build-mocha/README.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,46 @@
1+
A gulp-core-build plugin which will execute and provide coverage reports for Mocha unit tests
2+
13
# gulp-core-build-mocha [![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-mocha.svg)](https://badge.fury.io/js/gulp-core-build-mocha)
24

35
[![Build Status](https://travis-ci.org/Microsoft/gulp-core-build-mocha.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build-mocha) [![Dependencies](https://david-dm.org/Microsoft/gulp-core-build-mocha.svg)](https://david-dm.org/Microsoft/gulp-core-build-mocha)
6+
7+
# Description
8+
9+
**gulp-core-build-mocha** is a gulp-core-build plugin which will automatically execute a set of
10+
unit test files using the mocha test suite.
11+
12+
# MochaTask
13+
## Usage
14+
15+
Simply create a file which ends in `.test.js`. Next, register the Mocha task to gulp-core-build.
16+
17+
A coverage report is both written to the console and to a folder on disk.
18+
19+
## Configuration
20+
21+
### testMatch
22+
23+
Sets the glob pattern which is used to locate the files to run tests on.
24+
25+
**Default:** 'lib/\*\*/\*.test.js'
26+
27+
### reportDir
28+
29+
The folder in which to store the coverage reports.
30+
31+
**Default:** 'coverage'
32+
33+
# InstrumentTask
34+
## Usage
35+
36+
This task selects which files should be covered by the code coverage tool.
37+
38+
## Configuration
39+
### coverageMatch
40+
An array of globs which define which files should be included in code coverage reports.
41+
42+
**Default:** `['lib/**/*.js', '!lib/**/*.test.js']`
43+
44+
# License
45+
46+
MIT

‎gulp-core-build-sass/README.md‎

Lines changed: 35 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,31 +2,43 @@
22

33
[![Build Status](https://travis-ci.org/Microsoft/gulp-core-build-sass.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build-sass) [![Dependencies](https://david-dm.org/Microsoft/gulp-core-build-sass.svg)](https://david-dm.org/Microsoft/gulp-core-build-sass)
44

5+
# Description
56
`gulp-core-build-sass` is a plugin for `gulp-core-build` which introduces the ability to compile SASS files to CSS.
67

7-
# Tasks
8-
## SassTask
8+
# SassTask
99

10-
### Description
10+
## Usage
1111
This task invokes `gulp-sass` to compile source SASS files into a CommonJS module which uses `load-themed-styles` to load styles onto the page. If the `libAmdFolder` is specified globally, this task will also output an AMD module. Various templates may be specified.
1212

13-
### Config
14-
```typescript
15-
interface ISassTaskConfig {
16-
sassMatch?: string[];
17-
commonModuleTemplate: string;
18-
amdModuleTemplate: string;
19-
}
20-
```
21-
* **
22-
23-
Usage (and defaults):
24-
```typescript
25-
sass.setConfig({
26-
sassMatch: [
27-
'src/**/*.scss'
28-
],
29-
commonModuleTemplate: "require('load-themed-styles').loadStyles(<%= content %>);",
30-
amdModuleTemplate: "define(['load-themed-styles'], function(loadStyles) { loadStyles.loadStyles(<%= content %>); });"
31-
});
32-
```
13+
## Config
14+
### preamble
15+
An optional parameter for text to include in the generated typescript file.
16+
17+
**Default:** `'/* tslint:disable */'`
18+
19+
### postamble
20+
An optional parameter for text to include at the end of the generated typescript file.
21+
22+
**Default:** `'/* tslint:enable */'`
23+
24+
### sassMatch
25+
An array of glob patterns for locating SASS files.
26+
27+
**Default:** `['src/**/*.scss']`
28+
29+
### useCSSModules
30+
If this option is specified, files ending with `.module.scss` extension will automatically
31+
generate a corresponding TypeScript file. All classes will be appended with a hash
32+
to help ensure uniqueness on a page. This file can be imported directly, and will
33+
contain an object describing the mangled class names.
34+
35+
**Default:** `false`
36+
37+
### dropCssFiles
38+
If this is false, then we do not create `.css` files in the `lib` directory.
39+
40+
**Default:** `false`
41+
42+
# License
43+
44+
MIT

0 commit comments

Comments
 (0)