{"id":16252,"library":"tsc-prog","title":"Programmatic TypeScript Compiler","description":"`tsc-prog` is a JavaScript/TypeScript library designed to programmatically build TypeScript projects. It offers a flexible API for invoking the TypeScript compiler (`tsc`) with granular control over the build process, going beyond simple CLI execution. This library is particularly suited for complex production build pipelines where custom logic, pre-build steps, or post-build steps are required. Key features include a simplified `build` function, direct access to TypeScript's `Program` creation and `emit` steps, and powerful addons. These addons address common TypeScript build pain points like cleaning output directories (`clean` option), copying non-TypeScript assets to the output directory (`copyOtherToOutDir`), and bundling type definitions into a single `.d.ts` file (`bundleDeclaration`). As of version 2.3.0, `tsc-prog` primarily operates as a CommonJS module and requires `typescript@>=4` as a peer dependency. While it doesn't specify a strict release cadence, updates appear as needed to support new TypeScript features or address build complexities.","status":"active","version":"2.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/jeremyben/tsc-prog","tags":["javascript","typescript","tsc","compiler","programmatic"],"install":[{"cmd":"npm install tsc-prog","lang":"bash","label":"npm"},{"cmd":"yarn add tsc-prog","lang":"bash","label":"yarn"},{"cmd":"pnpm add tsc-prog","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency to provide the TypeScript compiler functionality.","package":"typescript","optional":false}],"imports":[{"note":"As of v2.x, tsc-prog is a CommonJS module. Direct ESM imports like 'import tsc from...' are not supported.","wrong":"import tsc from 'tsc-prog'","symbol":"tsc","correct":"const tsc = require('tsc-prog')"},{"note":"The primary API is accessed via the default CommonJS export. Named ESM imports are not available.","wrong":"import { build } from 'tsc-prog'","symbol":"build","correct":"const tsc = require('tsc-prog'); tsc.build({...})"},{"note":"Part of the CommonJS default export. Not available as a named ESM import.","wrong":"import { createProgramFromConfig } from 'tsc-prog'","symbol":"createProgramFromConfig","correct":"const tsc = require('tsc-prog'); tsc.createProgramFromConfig({...})"}],"quickstart":{"code":"const tsc = require('tsc-prog');\nconst path = require('path');\nconst fs = require('fs');\n\nconst basePath = path.resolve(__dirname, 'temp_project');\nconst tsconfigPath = path.join(basePath, 'tsconfig.json');\nconst srcDir = path.join(basePath, 'src');\nconst outDir = path.join(basePath, 'dist');\n\n// Ensure directories exist\nfs.mkdirSync(srcDir, { recursive: true });\nfs.mkdirSync(outDir, { recursive: true });\n\n// Create a dummy tsconfig.json\nfs.writeFileSync(tsconfigPath, JSON.stringify({\n  \"compilerOptions\": {\n    \"target\": \"ES2020\",\n    \"module\": \"CommonJS\",\n    \"outDir\": \"./dist\",\n    \"rootDir\": \"./src\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"forceConsistentCasingInFileNames\": true,\n    \"declaration\": true\n  },\n  \"include\": [\"src/**/*\"]\n}, null, 2));\n\n// Create a dummy TypeScript file\nfs.writeFileSync(path.join(srcDir, 'index.ts'), 'export function greet(name: string) { return `Hello, ${name}!`; }');\nfs.writeFileSync(path.join(srcDir, 'main.ts'), 'import { greet } from \"./index\"; console.log(greet(\"World\"));');\n\nconsole.log('Building TypeScript project with tsc-prog...');\n\ntsc.build({\n  basePath: basePath,\n  configFilePath: 'tsconfig.json',\n  compilerOptions: {\n    rootDir: 'src',\n    outDir: 'dist',\n    declaration: true,\n    skipLibCheck: true,\n  },\n  include: ['src/**/*'],\n  exclude: ['**/*.test.ts', '**/*.spec.ts'],\n  clean: ['dist'], // Clean previous build artifacts\n  copyOtherToOutDir: true, // Copy non-TS files if any (e.g., package.json)\n});\n\nconsole.log('Build complete. Check the temp_project/dist directory.');\n\n// Cleanup (optional)\n// fs.rmSync(basePath, { recursive: true, force: true });","lang":"typescript","description":"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."},"warnings":[{"fix":"Use `const tsc = require('tsc-prog')` to import the library.","message":"tsc-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.","severity":"gotcha","affected_versions":"<=2.3.0"},{"fix":"Monitor 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`).","message":"Future 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`.","severity":"breaking","affected_versions":">=3.0.0 (anticipated)"},{"fix":"Review 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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always specify `compilerOptions.outDir` when enabling `copyOtherToOutDir`.","message":"When using `copyOtherToOutDir`, `outDir` must be explicitly set in your `compilerOptions`. If `outDir` is missing, the option will have no effect or may cause errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `compilerOptions: { declaration: true, ... }` and ensure `bundleDeclaration.entryPoint` is correctly relative to your specified `outDir`.","message":"For `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `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.","cause":"The package is not installed or the `require()` path is incorrect.","error":"Cannot find module 'tsc-prog'"},{"fix":"Ensure you are using `const tsc = require('tsc-prog')` to correctly import the CommonJS module. If the problem persists, try reinstalling the package.","cause":"Attempting to use `tsc.build` after an incorrect import (e.g., a named ESM import on a CJS module) or a corrupted package installation.","error":"TypeError: tsc.build is not a function"},{"fix":"Add `outDir` to your `compilerOptions`. Example: `compilerOptions: { outDir: 'dist', ... }, copyOtherToOutDir: true`.","cause":"The `copyOtherToOutDir` option was enabled, but `compilerOptions.outDir` was not provided or was empty.","error":"Error: Parameter 'outDir' is required for 'copyOtherToOutDir'"},{"fix":"Set `declaration: true` in your `compilerOptions`. Example: `compilerOptions: { declaration: true, ... }, bundleDeclaration: { entryPoint: 'index.d.ts' }`.","cause":"The `bundleDeclaration` option was enabled, but `compilerOptions.declaration` was not set to `true`.","error":"Error: Parameter 'declaration' must be true in 'compilerOptions' for 'bundleDeclaration'"}],"ecosystem":"npm"}