diff --git a/README.md b/README.md index 4bc5bafedfb..52d5b624ec0 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,92 @@ -# gulp-core-build-typescript [![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-typescript.svg)](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-typescript) +@microsoft/gulp-core-build-typescript +===================================== +A set of gulp-core-build tasks for building TypeScript code. -[![Build Status](https://travis-ci.org/Microsoft/gulp-core-build-typescript.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build-typescript) [![Dependencies](https://david-dm.org/Microsoft/gulp-core-build-typescript.svg)](https://david-dm.org/Microsoft/gulp-core-build-typescript) +[![npm version](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-typescript.svg)](https://badge.fury.io/js/%40microsoft%2Fgulp-core-build-typescript) +[![Build Status](https://travis-ci.org/Microsoft/gulp-core-build-typescript.svg?branch=master)](https://travis-ci.org/Microsoft/gulp-core-build-typescript) +[![Dependencies](https://david-dm.org/Microsoft/gulp-core-build-typescript.svg)](https://david-dm.org/Microsoft/gulp-core-build-typescript) + +# Usage + +This collection of tasks is designed to be used with a gulp-core-build based build setup. It abstracts the TypeScript based build tasks used to build typescript code. + +The tasks exported are: + +* `typescript` - The task for building TypeScript into JavaScript. +* `tslint` - The task for linting the TypeScript code. +* `text` - Converts text files into JavaScript. + +To use these tasks in your build setup, simply import the package and add the task to a build task group. + +```typescript +import { task, serial, parallel, watch, CopyTask, IExecutable } from '@microsoft/gulp-core-build'; +import { typescript, tslint, text } from '@microsoft/gulp-core-build-typescript'; + +export * from '@microsoft/gulp-core-build'; +export * from '@microsoft/gulp-core-build-typescript'; + +// Examples of creating some copy tasks to be run pre/post build. +export const preCopy: CopyTask = new CopyTask(); +preCopy.name = 'pre-copy'; + +export const postCopy: CopyTask = new CopyTask(); +postCopy.name = 'post-copy'; + +// Define a task group. +task('build', serial(preCopy, parallel(tslint, typescript, text), postCopy)); +``` + +Some examples of build packages that use this task: + +* [@microsoft/web-library-build](https://github.com/Microsoft/web-library-build) +* [@microsoft/node-library-build](https://github.com/Microsoft/node-library-build) + +# Configuring task options + +Use the standard "setConfig" method on task instances to set their configuration options. Example: + +```typescript +import { typescript } from '@microsoft/gulp-core-build-typescript'; + +typescript.setConfig({ + typescript: require('typescript') +}); +``` + +## `typescript` task options + +See the `ITypeScriptTaskConfig` interface for the definition. + +* `failBuildOnErrors` (boolean, default: true) - Fails the build when errors occur. +* `sourceMatch` (string[]) - Glob matches for files to be included in the build. +* `staticMatch` (string[]) - Files that should by passed through (copied) to the build output. +* `reporter` - Custom TypeScript reporter. +* `typescript` - Optional override of the typescript compiler. Set this to the result of require('typescript'). + +## `tslint` task options + +See the `ITSLintTaskConfig` interface for the definition. + +* `lintConfig` (Object) - The tslint configuration object. +* `rulesDirectory` (string | string[]) - Directories to search for custom linter rules +* `sourceMatch` (string[]) - Provides the glob matches for files to be analyzed. +* `reporter` ((result: lintTypes.LintResult, file: gutil.File, options: ITSLintTaskConfig) => void;) - A function which reports errors to the proper location. Defaults to using the base GulpTask's this.fileError() function. +* `displayAsWarning` (boolean, default: false) - If true, displays warnings as errors. If the reporter function is overwritten, it should reference +* `remoteExistingRules` (boolean, default: false) - If true, the lintConfig rules which were previously set will be removed. This flag is useful for ensuring that there are no rules activated from previous calls to setConfig(). +* `useDefaultConfigAsBase` (boolean, default: true) - If false, does not use a default tslint configuration as the basis for creating the list of active rules. + +## `text` task options + +See the `ITextTaskConfig` interface for the definition. + +* `textMatch` (string[]) - Glob matches for files that should be converted into modules. + +# Related projects + +[@microsoft/gulp-core-build](https://github.com/Microsoft/gulp-core-build) - An abstraction around gulp that adds simplified serial/parallel task execution and a formal base task interface. + +[typescript](https://github.com/Microsoft/typescript) - The TypeScript compiler. + +# License + +[MIT](https://github.com/Microsoft/gulp-core-build-typescript/blob/master/LICENSE) diff --git a/package.json b/package.json index a698fc78129..8800c1b9156 100644 --- a/package.json +++ b/package.json @@ -9,20 +9,20 @@ "@microsoft/gulp-core-build": "~0.9.0", "gulp": "~3.9.1", "gulp-cache": "~0.4.5", - "gulp-changed": "~1.3.0", + "gulp-changed": "~1.3.2", "gulp-plumber": "~1.1.0", "gulp-sourcemaps": "~1.6.0", "gulp-texttojs": "~1.0.3", - "gulp-typescript": "~2.12.1", + "gulp-typescript": "~2.13.6", "gulp-util": "~3.0.7", - "lodash": "~4.12.0", + "lodash": "~4.15.0", "md5": "~2.1.0", "merge2": "~1.0.2", - "object-assign": "~4.0.1", + "object-assign": "~4.1.0", "through2": "~2.0.1", - "tslint": "~3.14.0", + "tslint": "~3.15.1", "tslint-microsoft-contrib": "~2.0.10", - "typescript": "1.8.9" + "typescript": "~1.8.10" }, "devDependencies": { "@microsoft/node-library-build": "~0.2.2" diff --git a/src/TextTask.ts b/src/TextTask.ts index aa09d9cf526..9ba1c1ce453 100644 --- a/src/TextTask.ts +++ b/src/TextTask.ts @@ -2,6 +2,9 @@ import { GulpTask } from '@microsoft/gulp-core-build'; import gulpType = require('gulp'); export interface ITextTaskConfig { + /** + * Glob matches for files that should be converted into modules. + */ textMatch?: string[]; } diff --git a/src/TypeScriptTask.ts b/src/TypeScriptTask.ts index 2342a9fdb96..db1c80135ef 100644 --- a/src/TypeScriptTask.ts +++ b/src/TypeScriptTask.ts @@ -4,7 +4,7 @@ import ts = require('gulp-typescript'); interface ITypeScriptErrorObject { diagnostic: { - messageText: string | { messageText: string }; + messageText: string | { messageText: string }; code: number; }; fullFilename: string; @@ -17,10 +17,33 @@ interface ITypeScriptErrorObject { } export interface ITypeScriptTaskConfig { + /** + * Fails the build when errors occur. + * @default true + */ failBuildOnErrors: boolean; + + /** + * Glob matches for files to be included in the build. + */ sourceMatch?: string[]; + + /** + * Glob matches for files to be passed through the build. + */ staticMatch?: string[]; + + /** + * Optional override for a custom reporter object to be passed into the TypeScript compiler. + */ reporter?: ts.Reporter; + + /** + * Optional override for the TypeScript compiler. + */ + /* tslint:disable:no-any */ + typescript?: any; + /* tslint:enable:no-any */ } export class TypeScriptTask extends GulpTask { @@ -30,15 +53,19 @@ export class TypeScriptTask extends GulpTask { failBuildOnErrors: true, reporter: { error: (error: ITypeScriptErrorObject): void => { + const filename: string = error.relativeFilename || error.fullFilename; + const line: number = error.startPosition ? error.startPosition.line : 0; + const character: number = error.startPosition ? error.startPosition.character : 0; + const code: number = error.diagnostic.code; const errorMessage: string = (typeof error.diagnostic.messageText === 'object') ? (error.diagnostic.messageText as { messageText: string }).messageText : error.diagnostic.messageText as string; this.fileError( - error.relativeFilename || error.fullFilename, - error.startPosition.line, - error.startPosition.character, - `TS${error.diagnostic.code}`, + filename, + line, + character, + 'TS' + code, errorMessage); } }, @@ -73,7 +100,8 @@ export class TypeScriptTask extends GulpTask { const tsCompilerOptions: ts.Params = assign({}, tsConfig.compilerOptions, { module: 'commonjs', - sortOutput: true + sortOutput: true, + typescript: this.taskConfig.typescript }); const tsProject: ts.Project = this._tsProject = this._tsProject || ts.createProject(tsCompilerOptions);