TypeScript Project Bundler

0.0.12 · abandoned · verified Tue Apr 21

ts-project-bundle is an experimental command-line interface (CLI) tool designed to simplify the bundling of TypeScript projects that leverage TypeScript's project references feature. Versioned at 0.0.12 and explicitly marked as a "prototype," it offers a basic mechanism to combine a main TypeScript project and its declared library dependencies into a single output directory, preserving their relative folder structure. Unlike full-featured bundlers such as Webpack or Rollup, ts-project-bundle focuses on the compilation and file restructuring aspects, relying on `tsc --build` for the initial compilation phase. Its primary differentiator is its direct integration with TypeScript project references, aiming to provide a lightweight solution for consolidating compiled output, particularly useful in monorepo environments where multiple interdependent TypeScript packages need to be deployed together. The tool's development appears to have ceased, with no significant updates since late 2022, indicating an abandoned status.

Common errors

```
Error: Project directory does not contain a tsconfig.json file.
```
cause The specified project directory (or current working directory if not specified) is not a valid TypeScript project or is missing its `tsconfig.json` file.

fix Ensure the directory where `ts-project-bundle` is run, or the directory specified by `--project`, contains a valid `tsconfig.json` file.
```
Error: No TypeScript project references found for project: [path]
```
cause The main project's `tsconfig.json` does not contain a `references` array, or the paths specified within it are invalid/unresolvable.

fix Verify that your main project's `tsconfig.json` includes valid `references` to its dependent TypeScript libraries, ensuring all paths are correct.
```
Command failed with exit code 1: tsc --build
```
cause TypeScript compilation failed due to syntax errors, missing dependencies, or incorrect `tsconfig.json` configurations in the main project or its referenced projects.

fix Address any compilation errors reported by `tsc --build` before attempting to bundle. Ensure all projects compile successfully independently.
```
Error: ENOENT: no such file or directory, stat '/path/to/missing/file'
```
cause This often occurs when the `--root` or `--project` paths are incorrectly specified, leading the bundler to look for files in the wrong locations or failing to resolve module paths correctly.

fix Carefully review the `--root` and `--project` arguments to ensure they correctly point to the monorepo root and the main project directory, respectively, relative to where the command is executed.

Warnings

breaking The package is explicitly marked as a 'prototype' (version 0.0.12) and is not intended for production use. Its API and behavior are unstable and subject to change without warning.
Fix: Use with caution for experimental purposes only. Do not rely on it for critical applications.
gotcha Development of `ts-project-bundle` appears to be abandoned, with the last commit in September 2022. There is no active maintenance, bug fixes, or feature development expected.
Fix: Consider alternatives for robust bundling solutions like `esbuild`, `Rollup.js`, or `Webpack` that are actively maintained. If used, be prepared to fork and maintain the codebase yourself.
gotcha This tool is fundamentally designed around TypeScript Project References. Projects not configured with `tsconfig.json` `references` will not leverage its core functionality and may fail.
Fix: Ensure your TypeScript projects are properly configured with project references and `tsconfig.json` files in all relevant directories.
gotcha The tool requires `npx tsc --build` to be run *before* `ts-project-bundle` to ensure all dependent projects are compiled. Skipping this step will result in bundling uncompiled or outdated code.
Fix: Always execute `npx tsc --build` in your main project directory before running `ts-project-bundle` to ensure all dependencies are built.

Install

npm install ts-project-bundle npm
yarn add ts-project-bundle yarn
pnpm add ts-project-bundle pnpm

Imports

ts-project-bundle
```
npx ts-project-bundle [options]
```
This package is a command-line interface (CLI) tool. It is executed directly via `npx` or a `package.json` script, and does not expose a programmatic API for `import` or `require`.

Quickstart

Demonstrates how to install and run `ts-project-bundle` on a minimal TypeScript project leveraging project references, compiling and consolidating its output into a single directory structure.

# Assume current working directory is a monorepo root: ~/my-monorepo
# This quickstart demonstrates creating a simple monorepo with two TypeScript packages,
# 'common' and 'api', where 'api' depends on 'common' via project references.

# 1. Create dummy package 'common'
mkdir -p packages/common/src
echo 'export const getGreeting = (name: string) => `Hello, ${name}!`;' > packages/common/src/index.ts
echo '{ "compilerOptions": { "outDir": "dist", "rootDir": "src", "target": "es2020", "module": "commonjs", "strict": true }, "include": ["src"] }' > packages/common/tsconfig.json
cd packages/common
npm init -y # Initialize common package
cd ../.. # Back to monorepo root

# 2. Create dummy package 'api' that depends on 'common'
mkdir -p packages/api/src
echo 'import { getGreeting } from "@myorg/common"; console.log(getGreeting("World"));' > packages/api/src/index.ts
echo '{ "compilerOptions": { "outDir": "dist", "rootDir": "src", "target": "es2020", "module": "commonjs", "strict": true, "baseUrl": ".", "paths": { "@myorg/common": ["../common/src"] } }, "references": [{ "path": "../common" }], "include": ["src"] }' > packages/api/tsconfig.json
cd packages/api
npm init -y # Initialize api package
npm install --save-dev ts-project-bundle typescript # Install ts-project-bundle and TS locally

# 3. Crucial: Compile the project and its references using tsc --build
npx tsc --build

# 4. Run ts-project-bundle from the 'api' package
# --root points to the monorepo root (where 'packages' is)
# --project points to the current 'api' directory
# --out specifies the output folder relative to the project (api)
npx ts-project-bundle --root=../../ --project=. --out=./out-bundle

echo "\nCheck the 'packages/api/out-bundle' directory for the bundled output."

view raw JSON →