ZetCode

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.

src/user.ts
export interface User {
    name: string;
    age: number;
}

export function describe(user: User): string {
    return `${user.name} is ${user.age} years old`;
}
src/main.ts
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.

tsconfig.json
{
    "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.

gulpfile.mjs
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.

src/main.ts
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

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Gulp tutorials.