Gulp TypeScript Plugin

Common errors

• TypeError: project.src is not a function

  cause Attempting to use `ts.createProject()` without invoking it as a function or incorrectly accessing its properties.
  fix Ensure `ts.createProject()` is called to create the project instance, e.g., `const tsProject = ts.createProject('tsconfig.json');`, and then use `tsProject()` as the gulp plugin, e.g., `gulp.src('src/**/*.ts').pipe(tsProject()).js.pipe(...)`.

• Error: Not a vinyl file. Make sure that you're not using .js or .d.ts files in your gulp.src statement when using `allowJs` or `declaration`

  cause `gulp-typescript` typically expects `.ts` or `.tsx` files as input unless `allowJs` is enabled. This error can occur if you pass already compiled JS/DTS files to the TypeScript stream without proper configuration.
  fix Verify that your `gulp.src()` glob pattern only selects TypeScript source files (`.ts`, `.tsx`). If you intend to compile JavaScript files, ensure `allowJs: true` is set in your `tsconfig.json` or `createProject` options.

• TS####: [TypeScript Compilation Error Message]

  cause A TypeScript compilation error occurred, and `gulp-typescript` (since v5) is configured to crash the process on error in non-watch mode.
  fix Correct the TypeScript code identified by the error message. For development and watch mode, consider using `gulp-plumber` before the `tsProject()` pipe to prevent the stream from stopping on errors, allowing continuous watch and reporting.

• Error: Input file must be a TS file!

  cause Attempting to pass non-TypeScript files (e.g., JavaScript files) to the `gulp-typescript` stream without `allowJs` enabled in the compiler options.
  fix Either ensure `gulp.src` only selects `.ts` or `.tsx` files, or enable the `allowJs` option in your `tsconfig.json` or `ts.createProject` configuration if you intend to process JavaScript files.

Warnings

• breaking Starting with v4.0.0 and further solidified in v5.0.0, `gulp-typescript` requires Gulp 4. Older versions of Gulp are not supported. Additionally, `gulp-util` dependency was removed in v4.0.0.
  Fix: Ensure your project's `gulp` dependency is `^4.0.0` or higher. Upgrade your `gulpfile.js` syntax to Gulp 4 API if necessary.
• breaking In v5.0.0, the behavior of compiler errors changed. Outside of watch mode, the Gulp process will now exit when a TypeScript compiler error occurs, aligning with Gulp's new error handling. In watch mode, the process continues.
  Fix: Handle errors appropriately within your Gulp task, for example, by using `gulp-plumber` to prevent the stream from stopping on errors in watch mode, or by ensuring your TypeScript code is error-free for non-watch builds.
• gotcha `gulp-typescript` does not handle sourcemap options directly. Options like `sourceMap`, `inlineSourceMap`, `inlineSources` are unsupported. Instead, `gulp-sourcemaps` should be used.
  Fix: Pipe your TypeScript stream through `gulp-sourcemaps.init()` before `tsProject()` and `gulp-sourcemaps.write()` after the `.js` stream. Example provided in the quickstart.
• gotcha The `watch` compiler option is not supported by `gulp-typescript`. Incremental compilation is managed internally by `ts.createProject()`, and file watching should be handled by `gulp.watch()`.
  Fix: Remove the `watch` option from your `tsconfig.json` or `ts.createProject` options. Implement file watching using `gulp.watch` to trigger compilation tasks.
• breaking v6.0.0-alpha.1 is a pre-release version. It may introduce further breaking changes not yet fully documented or stable. Use with caution in production environments.
  Fix: For production, prefer the latest stable v5.x release. If using v6 alpha, closely monitor release notes for breaking changes and update dependencies as advised.
• breaking When compiling with the `declaration: true` option, `gulp-typescript` outputs two streams: one for JavaScript (`.js`) and one for declaration files (`.dts`). Both must be piped to `gulp.dest()` separately.
  Fix: After piping through `tsProject()`, append `.js.pipe(gulp.dest('output'))` for JavaScript and `.dts.pipe(gulp.dest('output'))` for declaration files to ensure both are written to disk.

Install

• npm install gulp-typescript npm
• yarn add gulp-typescript yarn
• pnpm add gulp-typescript pnpm

Imports

• ts
  wrong:

  import ts from 'gulp-typescript';

  correct:

  const ts = require('gulp-typescript');

  Gulpfiles are typically CommonJS modules. While technically possible to use ESM in Gulp with configuration, `require` is the standard and explicitly documented way to import `gulp-typescript`.
• createProject
  wrong:

  const tsProject = require('gulp-typescript').createProject('tsconfig.json');

  correct:

  const tsProject = ts.createProject('tsconfig.json');

  The `createProject` function is a static method on the main `ts` export. It's used for incremental builds and reading `tsconfig.json`.
• reporter

  ts.reporter.full()

  Reporters are accessed as properties of the main `ts` object, e.g., `ts.reporter.full()` or `ts.reporter.defaultReporter()` for logging compilation output. These are typically used in the `.pipe()` chain or as part of error handling.

Quickstart

Demonstrates how to compile TypeScript files using `gulp-typescript` with sourcemaps and `tsconfig.json` support, outputting both JavaScript and declaration files. It also includes a basic watch task for development.

import gulp from 'gulp';
import ts from 'gulp-typescript';
import sourcemaps from 'gulp-sourcemaps';

// Create a TypeScript project instance, optionally reading a tsconfig.json
const tsProject = ts.createProject('tsconfig.json', {
  // Override options from tsconfig.json or define new ones
  // For example, force ES2017 target if tsconfig is older
  target: 'ES2017',
  declaration: true // Generate .d.ts files
});

function compileTypeScript() {
  return gulp.src('src/**/*.ts') // Source TypeScript files
    .pipe(sourcemaps.init()) // Initialize sourcemaps
    .pipe(tsProject()) // Compile TypeScript
    .js // Get JavaScript stream
    .pipe(sourcemaps.write('.')) // Write sourcemaps to same directory
    .pipe(gulp.dest('dist')) // Output JavaScript files
    .dts // Get Declaration stream
    .pipe(gulp.dest('dist')); // Output Declaration files
}

// Define a watch task for continuous compilation during development
function watchTypeScript() {
  gulp.watch('src/**/*.ts', compileTypeScript);
}

export const build = gulp.series(compileTypeScript);
export const watch = gulp.series(compileTypeScript, watchTypeScript);
export default build;