{"id":16047,"library":"gulp-typescript","title":"Gulp TypeScript Plugin","description":"gulp-typescript is a Gulp plugin designed for integrating TypeScript compilation into Gulp build workflows, offering features like incremental compilation and project reference support. The package is currently in an active development phase, with v5.0.1 being the latest stable release and v6.0.0-alpha.1 actively being developed. New releases, including alphas and minor fixes, are frequent. It serves as a key tool for developers who leverage Gulp for task automation and need to compile TypeScript, providing a direct interface to TypeScript's compiler options and supporting `tsconfig.json` configurations. Its main differentiators include tight integration with Gulp's streaming API, efficient incremental compilation, and support for advanced TypeScript features like custom transformers introduced in v5.","status":"active","version":"6.0.0-alpha.1","language":"javascript","source_language":"en","source_url":"https://github.com/ivogabe/gulp-typescript","tags":["javascript","typescript","gulpplugin","incremental compilation","ts","tsc","compile","compiler","transpile"],"install":[{"cmd":"npm install gulp-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add gulp-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add gulp-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the underlying TypeScript compiler for processing TS files.","package":"typescript","optional":false},{"reason":"The core task runner that gulp-typescript integrates with, specifically Gulp 4 and above.","package":"gulp","optional":false}],"imports":[{"note":"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`.","wrong":"import ts from 'gulp-typescript';","symbol":"ts","correct":"const ts = require('gulp-typescript');"},{"note":"The `createProject` function is a static method on the main `ts` export. It's used for incremental builds and reading `tsconfig.json`.","wrong":"const tsProject = require('gulp-typescript').createProject('tsconfig.json');","symbol":"createProject","correct":"const tsProject = ts.createProject('tsconfig.json');"},{"note":"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.","symbol":"reporter","correct":"ts.reporter.full()"}],"quickstart":{"code":"import gulp from 'gulp';\nimport ts from 'gulp-typescript';\nimport sourcemaps from 'gulp-sourcemaps';\n\n// Create a TypeScript project instance, optionally reading a tsconfig.json\nconst tsProject = ts.createProject('tsconfig.json', {\n  // Override options from tsconfig.json or define new ones\n  // For example, force ES2017 target if tsconfig is older\n  target: 'ES2017',\n  declaration: true // Generate .d.ts files\n});\n\nfunction compileTypeScript() {\n  return gulp.src('src/**/*.ts') // Source TypeScript files\n    .pipe(sourcemaps.init()) // Initialize sourcemaps\n    .pipe(tsProject()) // Compile TypeScript\n    .js // Get JavaScript stream\n    .pipe(sourcemaps.write('.')) // Write sourcemaps to same directory\n    .pipe(gulp.dest('dist')) // Output JavaScript files\n    .dts // Get Declaration stream\n    .pipe(gulp.dest('dist')); // Output Declaration files\n}\n\n// Define a watch task for continuous compilation during development\nfunction watchTypeScript() {\n  gulp.watch('src/**/*.ts', compileTypeScript);\n}\n\nexport const build = gulp.series(compileTypeScript);\nexport const watch = gulp.series(compileTypeScript, watchTypeScript);\nexport default build;","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure your project's `gulp` dependency is `^4.0.0` or higher. Upgrade your `gulpfile.js` syntax to Gulp 4 API if necessary.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Pipe your TypeScript stream through `gulp-sourcemaps.init()` before `tsProject()` and `gulp-sourcemaps.write()` after the `.js` stream. Example provided in the quickstart.","message":"`gulp-typescript` does not handle sourcemap options directly. Options like `sourceMap`, `inlineSourceMap`, `inlineSources` are unsupported. Instead, `gulp-sourcemaps` should be used.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Remove the `watch` option from your `tsconfig.json` or `ts.createProject` options. Implement file watching using `gulp.watch` to trigger compilation tasks.","message":"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()`.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0-alpha.1"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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(...)`.","cause":"Attempting to use `ts.createProject()` without invoking it as a function or incorrectly accessing its properties.","error":"TypeError: project.src is not a function"},{"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.","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.","error":"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`"},{"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.","cause":"A TypeScript compilation error occurred, and `gulp-typescript` (since v5) is configured to crash the process on error in non-watch mode.","error":"TS####: [TypeScript Compilation Error Message]"},{"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.","cause":"Attempting to pass non-TypeScript files (e.g., JavaScript files) to the `gulp-typescript` stream without `allowJs` enabled in the compiler options.","error":"Error: Input file must be a TS file!"}],"ecosystem":"npm"}