tsbuild/readme.md

@git.zone/tsbuild

🚀 A powerful, modern TypeScript build tool with smart defaults and full tsconfig.json support

A production-ready TypeScript compiler that combines flexibility with safety. Built for modern JavaScript development with ESNext, NodeNext modules, and automatic decorator support.

Why tsbuild?

• ✅ Smart tsconfig.json Integration - Respects all your compiler options with intelligent merging
• ✅ Protected Defaults - Critical build settings are safeguarded while staying flexible
• ✅ Zero Config - Works perfectly without tsconfig.json
• ✅ Glob Pattern Support - Compile multiple directories with a single command
• ✅ Dependency-Aware - Automatically orders compilation based on module dependencies
• ✅ Type Checking - Validate code without emitting files
• ✅ CI/CD Ready - JSON output mode and proper exit codes
• ✅ Library Safe - Never calls process.exit() in library code
• ✅ Modern Defaults - ESNext, NodeNext modules, decorators out of the box

Install

npm install @git.zone/tsbuild --save-dev

or with pnpm:

pnpm install @git.zone/tsbuild --save-dev

Quick Start

CLI Usage

Compile your TypeScript project:

npx tsbuild

Compiles ./ts/**/*.ts → ./dist_ts/

Custom directories:

npx tsbuild custom src utils

Compiles:

• ./src/**/*.ts → ./dist_src/
• ./utils/**/*.ts → ./dist_utils/

Auto-discover and compile in dependency order:

npx tsbuild tsfolders

Finds all ts_* folders and compiles them respecting dependencies.

Programmatic Usage

Basic compilation:

import { compileFileArray } from '@git.zone/tsbuild';

await compileFileArray([
  './src/index.ts',
  './src/utils.ts'
]);

Production-ready with error tracking (recommended):

import { compileFileArrayWithErrorTracking } from '@git.zone/tsbuild';

const result = await compileFileArrayWithErrorTracking([
  './src/**/*.ts'
], {
  target: 'ES2022',
  module: 'NodeNext'
});

if (result.hasErrors) {
  console.error('Compilation failed!');
  console.error('Files with errors:', result.fileCount);
  process.exit(1);
}

console.log('✅ Compilation successful!');

Advanced glob compilation:

import { compileGlobStringObject } from '@git.zone/tsbuild';

await compileGlobStringObject({
  './ts/**/*.ts': './dist_ts',
  './ts_web/**/*.ts': './dist_web'
}, {
  target: 'ES2022',
  module: 'ESNext'
});

CLI Commands

1. Default Build

npx tsbuild [options]

Compiles all TypeScript files from ./ts/ to ./dist_ts/

Options:

• --web - Include web-specific compilation
• --skiplibcheck - Skip type checking of declaration files (shows 5-second warning)
• --confirmskiplibcheck - Skip lib check without warning
• --disallowimplicitany - Disallow implicit any types
• --commonjs - Use CommonJS instead of ESNext modules
• --json - Output results as JSON (for CI/CD)
• --quiet - Suppress console output

Examples:

# Standard build
npx tsbuild

# Build with JSON output for CI
npx tsbuild --json --quiet

# CommonJS build
npx tsbuild --commonjs

2. Custom Directories

npx tsbuild custom <dir1> <dir2> ... [options]

Compile specific directories to their corresponding dist_ folders.

Examples:

# Compile src and utils
npx tsbuild custom src utils
# Creates: ./dist_src/ and ./dist_utils/

# Multiple directories with options
npx tsbuild custom api models services --commonjs

3. TSFolders (Dependency-Aware)

npx tsbuild tsfolders [options]

Automatically discovers and compiles all ts_* folders in dependency order:

1. Prioritizes ts_interfaces and ts_shared first
2. Reads tspublish.json for order property
3. Compiles in correct sequence

Example output:

compiling in this order:
[ 'ts_interfaces', 'ts_shared', 'ts_core', 'ts_utils', 'ts_modules' ]

🔨 [1/5] Compiling ts_interfaces...
✅ [1/5] Task completed in 1234ms
...

4. Emit Check

npx tsbuild emitcheck <file_or_pattern> [more...] [options]

Validates TypeScript files can be compiled without actually emitting them.

Examples:

# Check specific files
npx tsbuild emitcheck src/main.ts src/utils.ts

# Check with glob patterns
npx tsbuild emitcheck "src/**/*.ts" "test/**/*.ts"

# CI/CD usage
npx tsbuild emitcheck "**/*.ts" --json

Exit codes:

• 0 - All files can be emitted
• 1 - One or more files have errors

5. Type Check

npx tsbuild check <pattern> [more...] [options]

Performs type checking without emitting files. Faster than emitcheck.

Examples:

# Check all TypeScript files
npx tsbuild check "ts/**/*.ts"

# Check multiple patterns
npx tsbuild check "src/**/*.ts" "test/**/*.ts"

# Check with specific options
npx tsbuild check "**/*.ts" --disallowimplicitany

API Reference

Core Functions

compileFileArray(files, options?, argv?)

Basic compilation of file array.

Parameters:

• files: string[] - File paths to compile
• options?: CompilerOptions - TypeScript compiler options
• argv?: any - CLI arguments object

Returns: Promise<any[]> - Compiled file results

Example:

import { compileFileArray } from '@git.zone/tsbuild';

await compileFileArray(
  ['./src/index.ts', './src/utils.ts'],
  { target: 'ES2022' }
);

compileFileArrayWithErrorTracking(files, options?, argv?, taskInfo?)

⭐ RECOMMENDED for production - Provides detailed error tracking and metrics.

Parameters:

• files: string[] - File paths to compile
• options?: CompilerOptions - TypeScript compiler options
• argv?: any - CLI arguments object
• taskInfo?: ITaskInfo - Task metadata for progress reporting

Returns: Promise<IErrorSummary> - Detailed error summary

IErrorSummary Interface:

interface IErrorSummary {
  hasErrors: boolean;
  errorCount: number;
  fileCount: number;
  errorsByFile: Record<string, Diagnostic[]>;
  generalErrors: Diagnostic[];
}

Example:

import { compileFileArrayWithErrorTracking } from '@git.zone/tsbuild';

const result = await compileFileArrayWithErrorTracking(
  ['./src/**/*.ts'],
  { target: 'ES2022', strict: true }
);

if (result.hasErrors) {
  console.error(`❌ ${result.errorCount} errors in ${result.fileCount} files`);

  // Show errors by file
  for (const [file, errors] of Object.entries(result.errorsByFile)) {
    console.error(`\n${file}:`);
    errors.forEach(err => console.error(`  - ${err.messageText}`));
  }

  process.exit(1);
}

console.log('✅ Compilation successful!');

compileGlobStringObject(globObject, options?, cwd?, argv?)

Most powerful API - Compile multiple glob patterns to different destinations.

Parameters:

• globObject: Record<string, string> - Maps glob patterns to output directories
• options?: CompilerOptions - TypeScript compiler options
• cwd?: string - Working directory (defaults to process.cwd())
• argv?: any - CLI arguments object

Returns: Promise<any[]> - Array of compilation results

Example:

import { compileGlobStringObject } from '@git.zone/tsbuild';

await compileGlobStringObject(
  {
    './ts/**/*.ts': './dist_ts',
    './ts_web/**/*.ts': './dist_web',
    './ts_node/**/*.ts': './dist_node'
  },
  {
    target: 'ES2022',
    module: 'NodeNext'
  }
);

checkTypes(files, options?, argv?)

Type check files without emitting. Fast validation.

Parameters:

• files: string[] - Files to check
• options?: CompilerOptions - Compiler options
• argv?: any - CLI arguments

Returns: Promise<IErrorSummary> - Error summary

Example:

import { checkTypes } from '@git.zone/tsbuild';

const result = await checkTypes(['./src/**/*.ts']);

if (result.hasErrors) {
  console.error('Type errors found!');
  process.exit(1);
}

emitCheck(files, options?, argv?)

Validate files can be emitted without actually emitting.

Example:

import { emitCheck } from '@git.zone/tsbuild';

const result = await emitCheck(['./src/index.ts']);

if (result.hasErrors) {
  console.error('Cannot emit these files!');
}

TsBuild Class

Object-oriented API with full control.

Constructor:

new TsBuild(
  fileNames?: string[],
  customOptions?: CompilerOptions,
  argvArg?: any,
  taskInfo?: ITaskInfo
)

Methods:

• compile() - Compile and emit files
• compileWithErrorTracking() - Compile with detailed error summary
• checkTypes() - Type check without emitting
• emitCheck() - Validate emit capability
• mergeCompilerOptions() - Merge options (public utility)

Example:

import { TsBuild } from '@git.zone/tsbuild';

const builder = new TsBuild(
  ['./src/**/*.ts'],
  { target: 'ES2022', strict: true }
);

const result = await builder.compileWithErrorTracking();

if (result.hasErrors) {
  console.error('Build failed!');
}

Configuration

tsconfig.json Support

tsbuild fully supports all compiler options from tsconfig.json. Your project configuration is respected and intelligently merged.

Example tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "verbatimModuleSyntax": true
  }
}

Configuration Priority (Merge Order)

When multiple configuration sources exist, they merge in this order (later overrides earlier):

1. Default Options - tsbuild's sensible defaults
2. tsconfig.json - All options from your tsconfig.json (if present)
3. Protected Defaults - Critical options for build integrity
4. Programmatic Options - Options passed to API functions
5. CLI Flags - Command-line arguments (highest priority)

Example:

// tsconfig.json has: { "target": "ES2020" }
// You call:
await compileFileArray(files, { target: 'ES2022' });

// Result: Uses ES2022 (programmatic overrides tsconfig.json)

Protected Options

To ensure build integrity, these options are protected from tsconfig.json override (but can be overridden programmatically or via CLI):

• outDir: 'dist_ts/' - Required for automatic path transformations
• noEmitOnError: true - Prevents broken builds from being emitted
• declaration: true - Ensures .d.ts files for library consumers
• emitDecoratorMetadata: true - Required for DI frameworks
• inlineSourceMap: true - Consistent debugging experience

Why? These settings ensure tsbuild works correctly and produces consumable output.

Override if needed:

// Override via programmatic API
await compileFileArray(files, {
  outDir: './custom_dist',
  noEmitOnError: false  // ⚠️ Not recommended
});

Default Compiler Options

When no tsconfig.json exists, tsbuild uses these modern defaults:

{
  declaration: true,              // Generate .d.ts files
  emitDecoratorMetadata: true,    // Support DI frameworks
  experimentalDecorators: true,   // Enable decorators
  inlineSourceMap: true,          // Debug-friendly
  noEmitOnError: true,            // Fail-fast on errors
  outDir: 'dist_ts/',             // Output directory
  module: ModuleKind.NodeNext,    // Modern Node.js modules
  target: ScriptTarget.ESNext,    // Latest JavaScript
  moduleResolution: ModuleResolutionKind.NodeNext,
  lib: ['lib.dom.d.ts', 'lib.es2022.d.ts'],
  noImplicitAny: false,           // Flexible for quick development
  esModuleInterop: true,          // CJS/ESM interop
  useDefineForClassFields: false, // Classic decorator behavior
  verbatimModuleSyntax: true,     // Explicit imports/exports
  baseUrl: './'
}

CLI Flags

Override any option via command-line:

• --skiplibcheck - Skip declaration file checking (shows 5-second warning)
• --confirmskiplibcheck - Skip without warning
• --disallowimplicitany - Enable strict any checking
• --commonjs - Use CommonJS modules
• --json - Output JSON (for CI/CD)
• --quiet - Suppress console output

Examples:

# Strict mode
npx tsbuild --disallowimplicitany

# CommonJS output
npx tsbuild --commonjs

# CI/CD pipeline
npx tsbuild --json --quiet > build-results.json

Path Resolution

tsbuild automatically transforms path mappings from your tsconfig.json:

tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@models/*": ["./ts_models/*"],
      "@utils/*": ["./ts_utils/*"]
    }
  }
}

Automatic transformation:

./ts_models/* → ./dist_ts_models/*
./ts_utils/*  → ./dist_ts_utils/*

This ensures imports work correctly in compiled output.

Advanced Usage

Error Handling Patterns

Pattern 1: Simple (throw on error)

import { compileFileArray } from '@git.zone/tsbuild';

try {
  await compileFileArray(['./src/**/*.ts']);
  console.log('✅ Build successful');
} catch (error) {
  console.error('❌ Build failed:', error);
  process.exit(1);
}

Pattern 2: Detailed tracking (recommended)

import { compileFileArrayWithErrorTracking } from '@git.zone/tsbuild';

const result = await compileFileArrayWithErrorTracking(['./src/**/*.ts']);

if (result.hasErrors) {
  console.error(`\n❌ Compilation failed with ${result.errorCount} errors in ${result.fileCount} files\n`);

  // Group errors by file
  for (const [file, errors] of Object.entries(result.errorsByFile)) {
    console.error(`📄 ${file}:`);
    errors.forEach(err => {
      const line = err.file?.getLineAndCharacterOfPosition(err.start!);
      console.error(`  Line ${line?.line}: ${err.messageText}`);
    });
  }

  process.exit(1);
}

console.log('✅ All files compiled successfully!');

Pattern 3: CI/CD Integration

import { compileFileArrayWithErrorTracking } from '@git.zone/tsbuild';

const result = await compileFileArrayWithErrorTracking(['./src/**/*.ts']);

// Output machine-readable JSON
console.log(JSON.stringify({
  success: !result.hasErrors,
  errorCount: result.errorCount,
  fileCount: result.fileCount,
  timestamp: new Date().toISOString()
}, null, 2));

process.exit(result.hasErrors ? 1 : 0);

Multi-Stage Builds

Compile different parts of your project with different configurations:

import { compileGlobStringObject } from '@git.zone/tsbuild';

// Stage 1: Compile shared interfaces
await compileGlobStringObject(
  { './ts_interfaces/**/*.ts': './dist_interfaces' },
  { declaration: true, emitDecoratorMetadata: false }
);

// Stage 2: Compile Node.js code
await compileGlobStringObject(
  { './ts_node/**/*.ts': './dist_node' },
  { target: 'ES2022', module: 'NodeNext' }
);

// Stage 3: Compile browser code
await compileGlobStringObject(
  { './ts_web/**/*.ts': './dist_web' },
  { target: 'ES2020', module: 'ESNext', lib: ['lib.dom.d.ts', 'lib.es2020.d.ts'] }
);

Watch Mode Integration

Integrate with file watchers for development:

import { compileFileArray } from '@git.zone/tsbuild';
import chokidar from 'chokidar';

const watcher = chokidar.watch('./ts/**/*.ts');

watcher.on('change', async (path) => {
  console.log(`📝 ${path} changed, recompiling...`);

  try {
    await compileFileArray([path]);
    console.log('✅ Recompiled successfully');
  } catch (error) {
    console.error('❌ Compilation error:', error);
  }
});

console.log('👀 Watching for changes...');

Custom Task Progress

Track compilation progress in your UI:

import { compileFileArrayWithErrorTracking } from '@git.zone/tsbuild';

const taskInfo = {
  taskIndex: 1,
  totalTasks: 5,
  taskName: 'Compiling Core Modules'
};

const result = await compileFileArrayWithErrorTracking(
  ['./ts_core/**/*.ts'],
  { target: 'ES2022' },
  undefined,
  taskInfo
);

// Output: 🔨 [1/5] Compiling Core Modules...
//         ✅ [1/5] Task completed in 2345ms

TypeScript Decorator Support

tsbuild has first-class decorator support out of the box:

// Works automatically with no configuration
@Injectable()
class UserService {
  constructor(
    @Inject('CONFIG') private config: Config,
    private logger: Logger
  ) {}
}

The following options are enabled by default:

• experimentalDecorators: true
• emitDecoratorMetadata: true

This means frameworks like NestJS, TypeORM, Inversify, and Angular work without extra setup.

CI/CD Integration

GitHub Actions

name: Build
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'

      - run: npm install
      - run: npx tsbuild --json --quiet > build-results.json

      - name: Check build results
        run: |
          if ! cat build-results.json | jq -e '.success' > /dev/null; then
            echo "Build failed!"
            cat build-results.json | jq '.errors'
            exit 1
          fi

GitLab CI

build:
  stage: build
  script:
    - npm install
    - npx tsbuild
  artifacts:
    paths:
      - dist_ts/

Package.json Scripts

{
  "scripts": {
    "build": "tsbuild",
    "build:watch": "tsbuild && chokidar 'ts/**/*.ts' -c 'tsbuild'",
    "build:prod": "tsbuild --disallowimplicitany",
    "typecheck": "tsbuild check 'ts/**/*.ts'",
    "pretest": "tsbuild emitcheck 'test/**/*.ts'"
  }
}

Troubleshooting

Common Issues

"Cannot find module" errors in compiled output

This happens when path mappings aren't configured correctly. Make sure your tsconfig.json includes:

{
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@myapp/*": ["./ts/*"]
    }
  }
}

tsbuild automatically transforms these to work in the output directory.

Decorator errors

If you see decorator-related errors, ensure:

1. experimentalDecorators: true in tsconfig.json
2. emitDecoratorMetadata: true for DI frameworks
3. You're using a compatible TypeScript version (4.0+)

Build succeeds but types are wrong

Run with strict checking:

npx tsbuild --disallowimplicitany

This catches implicit any types that can hide bugs.

Slow compilation

Use --skiplibcheck to skip declaration file checking:

npx tsbuild --confirmskiplibcheck

⚠️ Only use this if you trust your dependencies' type definitions.

Debug Mode

For troubleshooting, combine flags:

# See exactly what's happening
npx tsbuild --json | jq '.'

# Check types without emitting
npx tsbuild check "**/*.ts"

# Verify emit capability
npx tsbuild emitcheck "**/*.ts"

Best Practices

✅ DO

• Use compileFileArrayWithErrorTracking() for production builds
• Enable strict mode in tsconfig.json for better type safety
• Organize code in ts_* folders for automatic dependency ordering
• Use protected defaults - they exist for good reasons
• Type check in CI/CD with npx tsbuild check
• Version lock tsbuild in package.json

❌ DON'T

• Don't override noEmitOnError - broken builds cause runtime errors
• Don't skip lib check in production builds
• Don't ignore type errors - they indicate real problems
• Don't mix module formats - stick to NodeNext for Node.js projects
• Don't use --quiet without --json - you'll lose error information

Performance Tips

1. Use glob patterns instead of explicit file lists
2. Enable --skiplibcheck for faster development (not production!)
3. Compile in stages for large multi-package projects
4. Use tsfolders for automatic dependency ordering
5. Cache dist_* folders in CI/CD pipelines

Migration Guide

From tsc

Before (package.json):

{
  "scripts": {
    "build": "tsc"
  }
}

After:

{
  "scripts": {
    "build": "tsbuild"
  }
}

Your tsconfig.json continues to work! tsbuild respects all your settings.

From other build tools

tsbuild is a drop-in replacement focused on TypeScript compilation. If you need bundling, combine with your bundler:

{
  "scripts": {
    "build": "tsbuild && esbuild dist_ts/index.js --bundle --outfile=bundle.js"
  }
}

FAQ

Q: Does tsbuild bundle code? A: No, tsbuild compiles TypeScript to JavaScript. For bundling, use esbuild, webpack, or rollup after compilation.

Q: Can I use tsbuild with monorepos? A: Yes! Use tsbuild tsfolders to automatically compile all packages in dependency order.

Q: Does it work with decorators? A: Yes, decorator support is enabled by default (both experimentalDecorators and emitDecoratorMetadata).

Q: Can I disable the protected defaults? A: Yes, via programmatic API or CLI flags. But consider why they're protected first!

Q: Does tsbuild support incremental compilation? A: tsbuild respects TypeScript's incremental flag if you set it in tsconfig.json.

Q: Is tsbuild compatible with TypeScript 5.x? A: Yes, tsbuild works with all modern TypeScript versions.

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

Company Information

Task Venture Capital GmbH Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.