Node TypeScript Compiler Wrapper

4.0.0 · active · verified Sun Apr 19

node-typescript-compiler is a Node.js module that exposes the functionality of the TypeScript compiler (tsc) by spawning the tsc command-line tool as a child process. This allows developers to programmatically invoke tsc from within a Node.js script, enabling advanced build workflows such as compiling multiple variants of modules (e.g., Node/browser) with different compiler options. The current stable version is 4.0.0. While a formal release cadence is not specified, a maintenance badge from 2023 indicates ongoing support. A key differentiator is its simple, reliable wrapper around the tsc CLI, which properly catches and reports compilation errors. It treats `typescript` itself as a peer dependency, giving users explicit control over which tsc version is used. This design promotes a clear separation of concerns, ensuring that node-typescript-compiler acts primarily as an orchestrator for the standard TypeScript toolchain.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.
```
cause Attempting to use CommonJS `require()` to import `node-typescript-compiler` v4.x.

fix Migrate your project to ESM and use `import tsc from 'node-typescript-compiler';`, ensuring your `package.json` includes `"type": "module"` or files use `.mjs` extension. Alternatively, downgrade to `node-typescript-compiler@3` for CJS support.
```
Error: Command failed with exit code 1
```
cause The underlying `tsc` command invoked by `node-typescript-compiler` failed, likely due to compilation errors, a misconfigured `tsconfig.json`, or `tsc` not being found.

fix Ensure the `typescript` package is installed (`npm i --save-dev typescript`). Check your `tsconfig.json` for errors, or verify your source files compile correctly by running `tsc --project .` directly. Enable verbose output in `node-typescript-compiler` options (`verbose: true`) for more detailed error messages from `tsc`.
```
TypeError: tsc.compile is not a function
```
cause The `node-typescript-compiler` module was not imported correctly, or the imported `tsc` object does not contain the `compile` method, possibly due to a version mismatch or incorrect import syntax.

fix Verify you are using `import tsc from 'node-typescript-compiler';` and that the package is correctly installed in your `node_modules`.

Warnings

breaking Version 4.0.0 and later of `node-typescript-compiler` are pure ESM (ECMAScript Modules) only. CommonJS `require()` is no longer supported.
Fix: Update your project to use ESM `import` statements and ensure your Node.js environment is configured for ESM (e.g., by setting `"type": "module"` in `package.json`). Node.js version 12 or higher is required.
breaking `node-typescript-compiler` now requires Node.js version 12 or higher due to its transition to pure ESM.
Fix: Upgrade your Node.js runtime to version 12 or newer. For older Node.js versions, use `node-typescript-compiler@3`.
gotcha The `typescript` package is a peer dependency and must be installed separately as a sibling `devDependency`.
Fix: Install `typescript` alongside `node-typescript-compiler`: `npm i --save-dev typescript node-typescript-compiler`.
gotcha It is strongly recommended to have a working TypeScript setup (with `tsc` and `tsconfig.json`) configured before using `node-typescript-compiler`.
Fix: Verify your `tsconfig.json` and source files compile correctly by running `tsc --project .` directly in your terminal before integrating `node-typescript-compiler` into your build script.

Install

npm install node-typescript-compiler npm
yarn add node-typescript-compiler yarn
pnpm add node-typescript-compiler pnpm

Imports

tsc
wrong:
```
const tsc = require('node-typescript-compiler');
```
correct:
```
import tsc from 'node-typescript-compiler';
```
Since v4, this package is pure ESM, requiring Node.js >= 12. The default export is an object that contains the main `compile` function.
compile
wrong:
```
import { compile } from 'node-typescript-compiler';
```
correct:
```
import tsc from 'node-typescript-compiler'; await tsc.compile(...);
```
The `compile` function is a method accessed via the default-exported `tsc` object, not a direct named export. Attempting to destructure it will fail.
CommonJS usage
wrong:
```
const myCompiler = require('node-typescript-compiler');
```
correct:
CommonJS `require()` is not supported in version 4.0.0 and later. Ensure your project is configured for ESM or use an older major version (e.g., v3).

Quickstart

This quickstart compiles the current TypeScript project using the `tsconfig.json` located in the current directory.

import tsc from 'node-typescript-compiler';

async function compileProject() {
  try {
    console.log('Starting TypeScript compilation...');
    await tsc.compile({
      'project': '.' // Refers to tsconfig.json in the current directory
    });
    console.log('TypeScript compilation successful.');
  } catch (error) {
    console.error('TypeScript compilation failed:', error.message);
    process.exit(1);
  }
}

compileProject();

view raw JSON →