Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
tsc
✓ const tsc = require('tsc-prog')
✗ import tsc from 'tsc-prog'
As of v2.x, tsc-prog is a CommonJS module. Direct ESM imports like 'import tsc from...' are not supported.
build
✓ const tsc = require('tsc-prog'); tsc.build({...})
✗ import { build } from 'tsc-prog'
The primary API is accessed via the default CommonJS export. Named ESM imports are not available.
createProgramFromConfig
✓ const tsc = require('tsc-prog'); tsc.createProgramFromConfig({...})
✗ import { createProgramFromConfig } from 'tsc-prog'
Part of the CommonJS default export. Not available as a named ESM import.
This quickstart demonstrates how to use `tsc-prog.build` to compile a simple TypeScript project programmatically, including cleaning the output directory and configuring compiler options from a `tsconfig.json` file. It sets up a temporary project, compiles it, and outputs to a `dist` folder.
const tsc = require('tsc-prog');
const path = require('path');
const fs = require('fs');
const basePath = path.resolve(__dirname, 'temp_project');
const tsconfigPath = path.join(basePath, 'tsconfig.json');
const srcDir = path.join(basePath, 'src');
const outDir = path.join(basePath, 'dist');
// Ensure directories exist
fs.mkdirSync(srcDir, { recursive: true });
fs.mkdirSync(outDir, { recursive: true });
// Create a dummy tsconfig.json
fs.writeFileSync(tsconfigPath, JSON.stringify({
"compilerOptions": {
"target": "ES2020",
"module": "CommonJS",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"declaration": true
},
"include": ["src/**/*"]
}, null, 2));
// Create a dummy TypeScript file
fs.writeFileSync(path.join(srcDir, 'index.ts'), 'export function greet(name: string) { return `Hello, ${name}!`; }');
fs.writeFileSync(path.join(srcDir, 'main.ts'), 'import { greet } from "./index"; console.log(greet("World"));');
console.log('Building TypeScript project with tsc-prog...');
tsc.build({
basePath: basePath,
configFilePath: 'tsconfig.json',
compilerOptions: {
rootDir: 'src',
outDir: 'dist',
declaration: true,
skipLibCheck: true,
},
include: ['src/**/*'],
exclude: ['**/*.test.ts', '**/*.spec.ts'],
clean: ['dist'], // Clean previous build artifacts
copyOtherToOutDir: true, // Copy non-TS files if any (e.g., package.json)
});
console.log('Build complete. Check the temp_project/dist directory.');
// Cleanup (optional)
// fs.rmSync(basePath, { recursive: true, force: true });
Debug
Known issues
gotchatsc-prog is a CommonJS module. Ensure you use `require()` for imports in your Node.js projects, especially if your project is also CommonJS. Direct ESM `import` statements will fail unless explicitly transpiled or if Node.js runtime handles CJS interop for ESM, which is not guaranteed for older Node.js versions.fixUse `const tsc = require('tsc-prog')` to import the library. affects: <=2.3.0
breakingFuture versions (v3+) may transition to an ESM-first or ESM-only approach. This would be a breaking change, requiring updates to import statements and potentially project `type` configurations in `package.json`.fixMonitor release notes for major versions. If updating, convert `require()` calls to `import` statements and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
affects: >=3.0.0 (anticipated)
gotchaThe `clean` option has built-in protections preventing deletion of critical directories like `basePath`, current working directory, or `rootDir` and their parents. This is a safety feature, but if you intend to delete a parent directory that matches these patterns, the operation will be skipped or partially applied.fixReview the paths specified in `clean` and ensure they are explicitly child directories of protected paths if you wish them to be removed. For example, clearing 'dist' inside 'basePath' is safe, but clearing 'basePath' itself is not allowed.
affects: >=1.0.0
gotchaWhen using `copyOtherToOutDir`, `outDir` must be explicitly set in your `compilerOptions`. If `outDir` is missing, the option will have no effect or may cause errors.fixAlways specify `compilerOptions.outDir` when enabling `copyOtherToOutDir`.
affects: >=1.0.0
gotchaFor `bundleDeclaration` to work, `compilerOptions.declaration` must be set to `true`, and `entryPoint` is relative to the *output* directory (`outDir`). Misconfiguring these can lead to failed bundling or incorrect output paths.fixSet `compilerOptions: { declaration: true, ... }` and ensure `bundleDeclaration.entryPoint` is correctly relative to your specified `outDir`. affects: >=1.0.0
Errors
Common errors & fixes
Cannot find module 'tsc-prog'
The package is not installed or the `require()` path is incorrect.
fixRun `npm install --save-dev tsc-prog` or `yarn add --dev tsc-prog`. Ensure your Node.js environment resolves modules correctly if using custom module resolution.
TypeError: tsc.build is not a function
Attempting to use `tsc.build` after an incorrect import (e.g., a named ESM import on a CJS module) or a corrupted package installation.
fixEnsure you are using `const tsc = require('tsc-prog')` to correctly import the CommonJS module. If the problem persists, try reinstalling the package. Error: Parameter 'outDir' is required for 'copyOtherToOutDir'
The `copyOtherToOutDir` option was enabled, but `compilerOptions.outDir` was not provided or was empty.
fixAdd `outDir` to your `compilerOptions`. Example: `compilerOptions: { outDir: 'dist', ... }, copyOtherToOutDir: true`. Error: Parameter 'declaration' must be true in 'compilerOptions' for 'bundleDeclaration'
The `bundleDeclaration` option was enabled, but `compilerOptions.declaration` was not set to `true`.
fixSet `declaration: true` in your `compilerOptions`. Example: `compilerOptions: { declaration: true, ... }, bundleDeclaration: { entryPoint: 'index.d.ts' }`. Audit
Dependencies
typescriptrequiredRequired as a peer dependency to provide the TypeScript compiler functionality.