Gulp TypeScript
last modified November 15, 2026
In this article we compile TypeScript with Gulp 5. We use the gulp-typescript plugin with a
tsconfig.json file, produce declaration files and source maps, fail the build on type errors, and
compare the plugin with a build that uses esbuild and tsc --noEmit.
TypeScript in a Gulp build
TypeScript adds static types to JavaScript; browsers and Node.js cannot run it, so the code has to be
compiled to JavaScript first. The compiler does two jobs: it checks the types and it removes them from the code
(and, if needed, lowers the syntax to an older JavaScript version). In Gulp there are two common approaches. The
gulp-typescript plugin runs the TypeScript compiler on a stream of .ts files and
reads the options from tsconfig.json. The other approach splits the two jobs: a fast tool such as
esbuild strips the types, and tsc --noEmit checks them.
Installing the project
We create a project and install Gulp, the plugin and TypeScript. We pin TypeScript to the 6.x series for the
plugin; the next section explains why. The esbuild package is used in the last example, and
npm pkg set type=module makes the project an ES module, as in the
Gulp esbuild tutorial.
$ mkdir gulp-ts $ cd gulp-ts $ npm init -y $ npm pkg set type=module $ npm i -D gulp gulp-typescript typescript@6 esbuild $ mkdir src
The example project
The sources are two TypeScript modules. The first one defines an interface and a function that uses it;
the second one imports them. In an ES module project, imports of local files use the .js extension,
because that is the name of the file that exists after the compilation.
export interface User {
name: string;
age: number;
}
export function describe(user: User): string {
return `${user.name} is ${user.age} years old`;
}
import { describe, type User } from './user.js';
const users: User[] = [
{ name: 'Alice', age: 30 },
{ name: 'Bob', age: 25 }
];
for (const user of users) {
console.log(describe(user));
}
The import of the User type is marked with type, which tells the compiler that
the import disappears from the output.
The tsconfig file
The options of the compiler are in tsconfig.json. The plugin reads this file, so the
same options are used by the Gulp build and by the tsc command and the editor. The
declaration option creates .d.ts files, strict turns on all strict type
checks, and nodenext is the module setting for Node.js ES modules.
{
"compilerOptions": {
"target": "es2022",
"module": "nodenext",
"moduleResolution": "nodenext",
"strict": true,
"declaration": true,
"sourceMap": true,
"outDir": "dist",
"rootDir": "src"
},
"include": ["src"]
}
The sources are in src and the compiled files go to dist.
The gulpfile
The gulpfile has several tasks that we look at one at a time. The createProject function reads
tsconfig.json once; the result, project, is a function that we put into the pipeline.
import { src, dest, series } from 'gulp';
import ts from 'gulp-typescript';
import { build as esbuild } from 'esbuild';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
const run = promisify(execFile);
const project = ts.createProject('tsconfig.json');
export function build() {
return src('src/**/*.ts')
.pipe(project())
.pipe(dest('dist'));
}
export function strict() {
return new Promise((resolve, reject) => {
const result = src('src/**/*.ts').pipe(project());
result.on('error', reject);
result.js.pipe(dest('dist-strict')).on('finish', resolve);
});
}
export function maps() {
return src('src/**/*.ts', { sourcemaps: true })
.pipe(project())
.pipe(dest('dist-maps', { sourcemaps: '.' }));
}
export function split() {
const result = src('src/**/*.ts').pipe(project());
return Promise.all([
new Promise((resolve, reject) => result.js.pipe(dest('dist-split/js'))
.on('finish', resolve).on('error', reject)),
new Promise((resolve, reject) => result.dts.pipe(dest('dist-split/types'))
.on('finish', resolve).on('error', reject))
]);
}
export async function typecheck() {
try {
await run('npx', ['tsc', '--noEmit']);
} catch (err) {
throw new Error(err.stdout.trim());
}
}
export async function transpile() {
await esbuild({
entryPoints: ['src/main.ts'],
outfile: 'dist-esbuild/main.js',
bundle: true,
format: 'esm',
sourcemap: true,
logLevel: 'info'
});
}
export const check = series(typecheck, transpile);
The gulpfile is an ES module (gulpfile.mjs), see the
ESM gulpfile tutorial.
Compiling TypeScript
The build task is the basic use: the .ts files go through project(), and the
stream that comes out has the JavaScript files and the declaration files, which dest writes.
return src('src/**/*.ts')
.pipe(project())
.pipe(dest('dist'));
The output has a .js and a .d.ts file for each module. The types are gone from the
JavaScript and the declaration file keeps them for the users of the library. The compiled program runs with Node.js.
$ npx gulp build
[13:45:26] Using gulpfile ~/Documents/prog/js/gulp-ts/gulpfile.mjs
[13:45:26] Starting 'build'...
[13:45:28] Finished 'build' after 1.25 s
$ ls dist
main.d.ts
main.js
user.d.ts
user.js
$ cat dist/main.js
import { describe } from './user.js';
const users = [
{ name: 'Alice', age: 30 },
{ name: 'Bob', age: 25 }
];
for (const user of users) {
console.log(describe(user));
}
$ cat dist/user.d.ts
export interface User {
name: string;
age: number;
}
export declare function describe(user: User): string;
$ node dist/main.js
Alice is 30 years old
Bob is 25 years old
The TypeScript 7 problem
The latest gulp-typescript release is an alpha that uses the JavaScript API of the compiler.
TypeScript 7 is a rewrite of the compiler in Go; it is much faster, but it has no such API yet, so the plugin
cannot work with it. If we install the latest typescript package, the gulpfile fails when it
creates the project, before any task starts.
$ npm i -D typescript@7 --silent $ npx tsc --version Version 7.0.2 $ npx gulp build 2>&1 | grep -v "^ *at " TypeError: typescript.convertCompilerOptionsFromJson is not a function
Source maps
Gulp 5 has built-in source map support, described in the Gulp source maps tutorial, and
it works with the plugin. We pass sourcemaps: true to src, so that the plugin can add the mapping
from the compiled code to the TypeScript source, and sourcemaps: '.' to dest, which writes the
map next to the file.
export function maps() {
return src('src/**/*.ts', { sourcemaps: true })
.pipe(project())
.pipe(dest('dist-maps', { sourcemaps: '.' }));
}
The compiled file ends with a sourceMappingURL comment, and the map refers to the original
.ts file, so a debugger shows the TypeScript code. The sourceMap option in
tsconfig.json is not what creates these maps in a Gulp pipeline.
$ npx gulp maps --silent $ ls dist-maps main.d.ts main.js main.js.map user.d.ts user.js user.js.map $ tail -n 1 dist-maps/main.js //# sourceMappingURL=main.js.map $ grep -o '"sources":\[[^]]*\]' dist-maps/main.js.map "sources":["../src/main.ts"]
Separating JavaScript and declarations
The stream returned by project() carries both kinds of files, but it also has two properties,
js and dts, which are streams of only the JavaScript files and only the declaration files.
This lets us write them into different directories, for example the code into dist/js and the types into
dist/types. The task has to wait for both streams, so it returns a promise that
resolves when both dest streams are finished.
const result = src('src/**/*.ts').pipe(project());
return Promise.all([
new Promise((resolve, reject) => result.js.pipe(dest('dist-split/js'))
.on('finish', resolve).on('error', reject)),
new Promise((resolve, reject) => result.dts.pipe(dest('dist-split/types'))
.on('finish', resolve).on('error', reject))
]);
The result is two directories, one for each kind of file.
$ npx gulp split --silent $ find dist-split -type f | sort dist-split/js/main.js dist-split/js/user.js dist-split/types/main.d.ts dist-split/types/user.d.ts
Type errors
The compiler reports type errors, but the plugin does not make the task fail by default. We add a line with a
wrong type to main.ts: a string is assigned to a variable of the type number. The
build task prints the error and then, because TypeScript still emits the code, reports that it
finished and exits with the code 0. A CI server would think that the build is fine.
import { describe, type User } from './user.js';
const users: User[] = [
{ name: 'Alice', age: 30 },
{ name: 'Bob', age: 25 }
];
for (const user of users) {
console.log(describe(user));
}
const count: number = 'many';
console.log(count);
The error shows the file, the line and the column, and the code of the error.
$ npx gulp build 2>&1; echo "exit code: $?" [13:45:35] Using gulpfile ~/Documents/prog/js/gulp-ts/gulpfile.mjs [13:45:35] Starting 'build'... src/main.ts(12,7): error TS2322: Type 'string' is not assignable to type 'number'. TypeScript: 1 semantic error TypeScript: emit succeeded (with errors) [13:45:36] Finished 'build' after 1.04 s exit code: 0
Failing the build on errors
The stream of the plugin emits an error event with the message "Compilation failed" when
there were errors, but Gulp does not see it in a simple .pipe() chain, as the
Gulp error handling tutorial explains. The strict task listens to the event and
rejects the promise, so the task fails and the exit code is non-zero. The task needs the stream of JavaScript files
(result.js), so that it can wait for them.
return new Promise((resolve, reject) => {
const result = src('src/**/*.ts').pipe(project());
result.on('error', reject);
result.js.pipe(dest('dist-strict')).on('finish', resolve);
});
The task now stops with the error, and nothing is written to the output directory.
$ npx gulp strict 2>&1; echo "exit code: $?" [13:45:36] Using gulpfile ~/Documents/prog/js/gulp-ts/gulpfile.mjs [13:45:36] Starting 'strict'... src/main.ts(12,7): error TS2322: Type 'string' is not assignable to type 'number'. TypeScript: 1 semantic error TypeScript: emit succeeded (with errors) [13:45:37] 'strict' errored after 980 ms [13:45:37] Error: TypeScript: Compilation failed exit code: 1
Type checking without the plugin
The second approach separates the two jobs. esbuild removes the types very quickly, but it does not check them;
the typecheck task runs tsc --noEmit and fails with the output of the compiler if there are
errors. The check task runs both in series, so the code is transpiled only when the types are
correct. The gulpfile above has the transpile task, which bundles main.ts with esbuild
as described in the Gulp esbuild tutorial.
export async function typecheck() {
try {
await run('npx', ['tsc', '--noEmit']);
} catch (err) {
throw new Error(err.stdout.trim());
}
}
export const check = series(typecheck, transpile);
With the type error still in main.ts the check task stops in typecheck and the
bundle is not built. This approach does not depend on the plugin, so it is not tied to the TypeScript 6 series. The two steps can also run in
parallel when the type check is only a gate and the bundle is needed quickly during development.
$ npx gulp check 2>&1; echo "exit code: $?" [13:45:38] Using gulpfile ~/Documents/prog/js/gulp-ts/gulpfile.mjs [13:45:38] Starting 'check'... [13:45:38] Starting 'typecheck'... [13:45:39] 'typecheck' errored after 1.18 s [13:45:39] Error: src/main.ts(12,7): error TS2322: Type 'string' is not assignable to type 'number'. [13:45:39] 'check' errored after 1.18 s exit code: 1
The fixed project
After we remove the wrong line, the same check task passes both steps. esbuild reads the
TypeScript files directly, because it knows the language from the extension, and writes the bundle with a source
map. The bundle runs like any JavaScript file.
$ npx gulp check [13:45:39] Using gulpfile ~/Documents/prog/js/gulp-ts/gulpfile.mjs [13:45:39] Starting 'check'... [13:45:39] Starting 'typecheck'... [13:45:41] Finished 'typecheck' after 1.22 s [13:45:41] Starting 'transpile'... [13:45:41] Finished 'transpile' after 9.66 ms [13:45:41] Finished 'check' after 1.23 s dist-esbuild/main.js 277b dist-esbuild/main.js.map 738b ⚡ Done in 2ms $ node dist-esbuild/main.js Alice is 30 years old Bob is 25 years old
Source
gulp-typescript on npm, TSConfig reference, esbuild and TypeScript
In this article we have compiled TypeScript with Gulp 5: we used gulp-typescript, wrote declaration
files and source maps, made the build fail on type errors, and compared the plugin with esbuild and
tsc --noEmit. See also the Gulp esbuild and Gulp Babel tutorials.
Author
List all Gulp tutorials.