TSBunch: TypeScript Bundler (TS to TS)

Common errors

• Error: Cannot find module 'module-name' in the bundled output

  cause TSBunch failed to correctly resolve or include a module due to unsupported import syntax or a file path issue. This often happens with dynamic imports or complex re-exports.
  fix Verify that all imported modules use supported `import` syntax as outlined in the TSBunch 'Caveats' section. Ensure module paths are relative and correct within the project structure.

• Bundling process hangs or takes an extremely long time without completing.

  cause This is a common symptom of circular dependencies within the TypeScript modules being bundled. TSBunch does not have mechanisms to detect or resolve these cycles, leading to infinite loops or deep recursion during string matching.
  fix Identify and refactor any circular dependencies in your project's module graph. Use `madge --circular --ts` or similar tools to help pinpoint these issues before running TSBunch.

• Unexpected token 'export' or 'import' in output file, or bundled code fails to compile TypeScript.

  cause The output `.ts` file contains syntax errors because TSBunch's string-based parsing incorrectly altered or failed to process certain import/export statements, or due to unsupported patterns like `export { default } from '...'`.
  fix Review the 'Caveats' section for partially supported or unsupported import/export syntax. Specifically, avoid direct `export default function/class` and use a `const` variable for the default export instead. Ensure all module exports are explicitly named and simple.

Warnings

• gotcha TSBunch uses string matching instead of an Abstract Syntax Tree (AST) for parsing. This means its support for the full ES module import/export specification is limited and might not behave as expected for all valid TypeScript module patterns.
  Fix: Review the 'Caveats' section in the TSBunch README for supported and unsupported import/export syntax. Adjust your module structure to conform to the supported patterns, typically favoring explicit named exports and avoiding dynamic imports or re-exports from other modules.
• gotcha Direct `export default function` or `export default class` declarations will have their names changed by TSBunch. This can lead to unexpected behavior if you rely on the original default export name.
  Fix: Instead of directly default exporting functions or classes, assign them to a `const` and then `export default` that constant. Example: `const MyFunc = () => {}; export default MyFunc;`
• gotcha TSBunch does not resolve circular dependencies. If your project contains circular imports, the bundling process may take an unusually long time or fail, leading to an unresponsive build process.
  Fix: Before bundling, ensure your TypeScript project's module graph is free of circular dependencies. Tools like `madge` or `depcheck` can help identify these cycles in your codebase.
• gotcha Dynamic `import()` expressions, type-only exports (`export type {}`), or re-exports (`export * from 'module'`) are not supported by TSBunch and will not be correctly processed.
  Fix: Refactor your code to use only explicit named imports and exports for modules that will be bundled. Avoid advanced module patterns that rely on dynamic loading or re-exporting namespaces.

Install

• npm install tsbunch npm
• yarn add tsbunch yarn
• pnpm add tsbunch pnpm

Imports

• tsbunch
  wrong:

  const tsbunch = require('tsbunch'); // For CJS

  correct:

  import tsbunch from 'tsbunch'; // For ESM

  The primary API is a default export, a function named `tsbunch`. The documentation exclusively uses CommonJS `require`, but an ESM import should also work if your environment supports it.

Quickstart

Demonstrates how to use the `tsbunch` function to bundle a TypeScript entry file, specify an output path, and include an optional declaration file, illustrating its core command-line usage.

import tsbunch from 'tsbunch';
import path from 'path';

// Simulate an entry file
// tsbunch expects actual files on disk
// For a runnable example, create these files first:
// 
// // src/moduleA.ts
// export const dataA = 'Hello from Module A!';
// 
// // src/entry.ts
// import { dataA } from './moduleA';
// namespace MyBundle {
//   console.log(dataA);
//   export const bundledMessage = `Bundled: ${dataA}`;
// }
// 
// // src/declarations.d.ts
// declare namespace Global {
//   const APP_VERSION: string;
// }

const entryFile = path.resolve(__dirname, 'src/entry.ts');
const outputFile = path.resolve(__dirname, 'out/bundle.ts');
const declarationFile = path.resolve(__dirname, 'src/declarations.d.ts');

// In a real scenario, you'd ensure 'src' and 'out' directories exist.
// For demonstration, we'll just show the call.

try {
  console.log('Attempting to bundle...');
  tsbunch(entryFile, outputFile, declarationFile);
  console.log(`Bundle created successfully at ${outputFile}`);
  console.log('You would typically inspect ' + outputFile + ' now.');
  console.log('Note: This code snippet assumes you have actual files for entry, output, and declarations.');
} catch (error) {
  console.error('Bundling failed:', error);
  console.error('Make sure your entry, output, and declaration file paths are correct and the files exist.');
}

// To run this: 
// 1. Create the files: src/moduleA.ts, src/entry.ts, src/declarations.d.ts
// 2. Install tsbunch: npm install --save-dev tsbunch
// 3. Run: node your-quickstart-file.js