Gulp stream integration with separate JavaScript and declaration file outputs for flexible build pipeline integration. The stream interface enables composition with other gulp plugins and complex build workflows.
Main compilation stream interface extending Node.js ReadWriteStream with specialized sub-streams for different output types.
interface ICompileStream extends NodeJS.ReadWriteStream {
/** Stream containing compiled JavaScript files */
js: stream.Readable;
/** Stream containing TypeScript declaration files (.d.ts) */
dts: stream.Readable;
}
type CompileStream = ICompileStream;Usage Examples:
import * as gulp from 'gulp';
import * as ts from 'gulp-typescript';
import * as merge from 'merge2';
import * as uglify from 'gulp-uglify';
import * as rename from 'gulp-rename';
// Basic stream separation
gulp.task('compile-separate-streams', () => {
const tsResult = gulp.src('src/**/*.ts')
.pipe(ts({
declaration: true,
target: 'ES2017',
module: 'commonjs'
}));
return merge([
tsResult.js.pipe(gulp.dest('dist/js')),
tsResult.dts.pipe(gulp.dest('dist/types'))
]);
});
// Process JavaScript stream with additional transformations
gulp.task('compile-and-minify', () => {
const tsResult = gulp.src('src/**/*.ts')
.pipe(ts({
target: 'ES5',
module: 'umd'
}));
return merge([
// Minify JavaScript output
tsResult.js
.pipe(uglify())
.pipe(rename({ suffix: '.min' }))
.pipe(gulp.dest('dist/js')),
// Copy declaration files as-is
tsResult.dts
.pipe(gulp.dest('dist/types'))
]);
});
// Different destinations for different streams
gulp.task('compile-multi-dest', () => {
const tsResult = gulp.src('src/**/*.ts')
.pipe(ts({
declaration: true,
outDir: 'build'
}));
return merge([
tsResult.js.pipe(gulp.dest('lib')), // JS to lib/
tsResult.dts.pipe(gulp.dest('types')) // Types to types/
]);
});Integration with gulp plugin ecosystem for complex build pipelines.
Usage Examples:
import * as gulp from 'gulp';
import * as ts from 'gulp-typescript';
import * as sourcemaps from 'gulp-sourcemaps';
import * as babel from 'gulp-babel';
import * as concat from 'gulp-concat';
import * as header from 'gulp-header';
// Source maps integration
gulp.task('compile-with-sourcemaps', () => {
return gulp.src('src/**/*.ts')
.pipe(sourcemaps.init())
.pipe(ts({
target: 'ES2015',
module: 'commonjs'
}))
.pipe(sourcemaps.write('.'))
.pipe(gulp.dest('dist'));
});
// Multi-stage compilation pipeline
gulp.task('compile-pipeline', () => {
const tsResult = gulp.src('src/**/*.ts')
.pipe(sourcemaps.init())
.pipe(ts({
target: 'ES2015',
module: 'commonjs',
declaration: true
}));
return merge([
// JavaScript pipeline: TS -> Babel -> Bundle -> Minify
tsResult.js
.pipe(babel({
presets: ['@babel/preset-env']
}))
.pipe(concat('bundle.js'))
.pipe(uglify())
.pipe(sourcemaps.write('.'))
.pipe(gulp.dest('dist')),
// Declaration pipeline: add header and copy
tsResult.dts
.pipe(header('// Auto-generated TypeScript declarations\n'))
.pipe(gulp.dest('dist/types'))
]);
});
// Conditional stream processing
gulp.task('compile-conditional', () => {
const isProduction = process.env.NODE_ENV === 'production';
const tsResult = gulp.src('src/**/*.ts')
.pipe(ts({
target: 'ES2017',
module: 'commonjs',
declaration: !isProduction // Only generate declarations in dev
}));
const streams = [
tsResult.js
.pipe(isProduction ? uglify() : util.noop())
.pipe(gulp.dest('dist'))
];
// Only include declaration stream in development
if (!isProduction) {
streams.push(
tsResult.dts.pipe(gulp.dest('dist/types'))
);
}
return merge(streams);
});Using project streams with file source management.
interface Project {
/**
* Get source files from tsconfig.json files/include/exclude patterns
* Only available for projects created with tsconfig.json
*/
src(): NodeJS.ReadWriteStream;
}Usage Examples:
import * as gulp from 'gulp';
import * as ts from 'gulp-typescript';
import * as merge from 'merge2';
const tsProject = ts.createProject('tsconfig.json');
// Use project.src() instead of gulp.src()
gulp.task('compile-project-src', () => {
const tsResult = tsProject.src()
.pipe(tsProject());
return merge([
tsResult.js.pipe(gulp.dest('dist')),
tsResult.dts.pipe(gulp.dest('types'))
]);
});
// Combine project sources with additional files
gulp.task('compile-mixed-sources', () => {
const projectFiles = tsProject.src();
const additionalFiles = gulp.src(['extra/**/*.ts']);
const tsResult = merge([projectFiles, additionalFiles])
.pipe(tsProject());
return merge([
tsResult.js.pipe(gulp.dest('dist')),
tsResult.dts.pipe(gulp.dest('types'))
]);
});
// Watch project files
gulp.task('watch-project', () => {
return gulp.watch(
// Watch files included by tsconfig.json
['src/**/*.ts', 'tsconfig.json'],
gulp.series('compile-project-src')
);
});Proper error handling for compilation streams to prevent build pipeline failures.
Usage Examples:
import * as gulp from 'gulp';
import * as ts from 'gulp-typescript';
import * as plumber from 'gulp-plumber';
// Basic error handling with plumber
gulp.task('compile-with-error-handling', () => {
return gulp.src('src/**/*.ts')
.pipe(plumber({
errorHandler: (error) => {
console.error('TypeScript compilation error:', error.message);
}
}))
.pipe(ts({
strict: true
}))
.pipe(gulp.dest('dist'));
});
// Custom error handling for streams
gulp.task('compile-custom-error-handling', () => {
const tsResult = gulp.src('src/**/*.ts')
.pipe(ts({
noImplicitAny: true
}, ts.reporter.nullReporter())); // Suppress default errors
// Handle errors on individual streams
return merge([
tsResult.js
.on('error', (error) => {
console.error('JavaScript compilation error:', error);
})
.pipe(gulp.dest('dist/js')),
tsResult.dts
.on('error', (error) => {
console.error('Declaration file error:', error);
})
.pipe(gulp.dest('dist/types'))
]);
});
// Gulp 3 compatibility error handling
gulp.task('compile-gulp3-compat', () => {
return gulp.src('src/**/*.ts')
.pipe(ts({
strict: true
}))
.on('error', () => {
// Prevent process crash in Gulp 3
// In Gulp 4, this is handled automatically
})
.pipe(gulp.dest('dist'));
});Common patterns and utilities for working with compilation streams.
Usage Examples:
import * as gulp from 'gulp';
import * as ts from 'gulp-typescript';
import * as merge from 'merge2';
import * as filter from 'gulp-filter';
import * as debug from 'gulp-debug';
// Stream debugging and monitoring
gulp.task('compile-with-debug', () => {
const tsResult = gulp.src('src/**/*.ts')
.pipe(debug({ title: 'TypeScript input:' }))
.pipe(ts({
declaration: true
}));
return merge([
tsResult.js
.pipe(debug({ title: 'JavaScript output:' }))
.pipe(gulp.dest('dist/js')),
tsResult.dts
.pipe(debug({ title: 'Declaration output:' }))
.pipe(gulp.dest('dist/types'))
]);
});
// Stream filtering and processing
gulp.task('compile-with-filtering', () => {
const tsResult = gulp.src('src/**/*.ts')
.pipe(ts({
declaration: true
}));
// Filter for specific files in streams
const testFilter = filter(['**', '!**/*.test.*'], { restore: true });
return merge([
tsResult.js
.pipe(testFilter) // Exclude test files
.pipe(gulp.dest('dist/js')),
tsResult.dts
.pipe(testFilter) // Exclude test declarations
.pipe(gulp.dest('dist/types'))
]);
});interface ICompileStream extends NodeJS.ReadWriteStream {
/** Stream containing compiled JavaScript files */
js: stream.Readable;
/** Stream containing TypeScript declaration files (.d.ts) */
dts: stream.Readable;
}
type CompileStream = ICompileStream;