tsbundle/readme.hints.md

tsbundle Hints and Findings

Bundler Architecture

• tsbundle uses a child process architecture where each bundler runs in a separate process
• Configuration is passed via environment variables as JSON (IEnvTransportOptions)
• The main class TsBundle spawns child processes using smartspawn.ThreadSimple

Bundler Implementations

• esbuild (default): Fully implemented, production ready, 2.2K minified
• rolldown: Implemented and working (beta), produces smallest bundles (1.5K minified)
• rspack: Implemented and working, webpack-compatible API, 6.1K minified
• rollup: Removed (was never implemented)
• parcel: Removed (was never implemented)

Adding New Bundlers

To add a new bundler, you need:

1. Update ICliOptions interface to include the bundler name
2. Add case in getBundlerPath() switch statement
3. Create mod_<bundler>/ directory with:
   • plugins.ts: Import and re-export the bundler
   • index.child.ts: Implement TsBundleProcess class with buildTest() and buildProduction()
4. Add bundler to package.json dependencies

Rolldown Specific Notes

• Rolldown is in beta (v1.0.0-beta.18) but working well
• API: Use rolldown() function directly, not rolldown.rolldown()
• Output options go in the write() method, not the initial config
• Uses dir and entryFileNames instead of file for output (handles dynamic imports)
• Includes inlineDynamicImports: true to avoid chunk splitting issues
• Produces smaller minified bundles than esbuild (1.5K vs 2.2K in tests)
• Supports TypeScript via resolve.tsconfigFilename

Rspack Specific Notes

• Rspack v1.3.15 - stable and production ready
• Uses webpack-compatible API (callback-based)
• Built-in SWC loader for TypeScript transpilation
• Produces larger bundles than esbuild/rolldown due to webpack runtime overhead
• Best choice if you need webpack compatibility or advanced features
• Supports ES modules output via experiments.outputModule: true

CLI Usage

• Default bundler: tsbundle (uses esbuild)
• Specify bundler: tsbundle --bundler=rolldown or tsbundle --bundler=rspack
• Production mode: tsbundle --production
• Combined: tsbundle --bundler=rolldown --production

Known Issues

• esbuild recently had splitting and tree-shaking disabled due to issues
• The README still mentions "a bundler using rollup" but uses esbuild by default