TS Bundle

0.3.0 verified Thu Apr 23 auth: no javascript abandoned

TS Bundle is a package bundler designed for TypeScript projects, aggregating multiple TypeScript files into a single output file. It is particularly useful for packaging library components, leveraging `references.d.ts` files to determine file order and dependencies. The current stable version, `0.3.0`, was last published over eight years ago, indicating that the project is no longer actively maintained. Its core functionality involves consolidating source files, optionally wrapping them in a specified root module, and enabling the inclusion of license headers. It provides a `preSave` hook for final output manipulation and an option to disable TSLint on the generated bundle. This tool predates modern bundlers like Webpack, Rollup, or esbuild, which offer more sophisticated features and better integration with contemporary TypeScript and JavaScript ecosystems.

Common errors

error Error: File not found: <your-src-file>.ts ↓

cause The source file specified in the `src` option of the configuration object does not exist at the provided path, or the path is incorrect.

fix

Verify that the path specified for src is correct and relative to where the ts-bundle script is executed, or provide an absolute path to the file.

error TypeError: Cannot read properties of undefined (reading 'bundle') OR TypeError: ts-bundle is not a function ↓

cause This error often occurs when attempting `const { bundle } = require('ts-bundle');` or `import { bundle } from 'ts-bundle';` because `ts-bundle` exports its main function as the default module export, not as a named property on an object.

fix

Use const bundle = require('ts-bundle'); for CommonJS or import bundle from 'ts-bundle'; for ESM interop to correctly import the bundling function, as the module itself is the function.

error TSxxxx: Cannot find name '...' OR TSxxxx: Property '...' does not exist on type '...' ↓

cause These are common TypeScript compilation errors that can arise if `ts-bundle`'s internal TypeScript version is incompatible with the source code's features, or if necessary declaration files (`.d.ts`) are missing or incorrectly referenced.

fix

Ensure that all required TypeScript declarations are available and correctly referenced via /// <reference path="..." />. If you are using very new TypeScript syntax or features, ts-bundle may not support them; in such cases, consider upgrading your bundler or migrating to a modern alternative.

Warnings

breaking The `ts-bundle` package has not been updated in over eight years. It is highly unlikely to support modern TypeScript features (e.g., advanced decorators, ESNext modules beyond ES5/ES6), newer ECMAScript syntax (like optional chaining or nullish coalescing), or recent Node.js runtime environments without encountering significant compatibility issues or unexpected behavior. ↓

fix For new projects or projects requiring modern TypeScript features, consider migrating to actively maintained and modern bundlers such as Webpack, Rollup, esbuild, or Parcel. These tools offer robust support for current language features and ecosystems.

gotcha This bundler relies heavily on the `references.d.ts` file and `/// <reference path="..." />` directives for ordering and dependency resolution of TypeScript files. Misconfigurations or outdated `references.d.ts` files can lead to incorrect bundling order, missing files, or compilation errors. ↓

fix Carefully review and maintain your `references.d.ts` file(s), ensuring all dependent files are correctly referenced and ordered. Ensure the `src` option points to the correct entry point that properly cascades references.

gotcha The output produced by `ts-bundle` is primarily CommonJS and lacks modern bundling features such as tree-shaking, code splitting, dynamic imports, or advanced minification strategies. These features are standard in contemporary bundlers and are crucial for optimizing bundle sizes and application performance. ↓

fix For optimized bundle sizes, better performance, and advanced bundling capabilities, it is strongly recommended to use modern bundlers. If you must use `ts-bundle`, external tools would be required for further optimization steps like minification.

deprecated The `ts-bundle` package is effectively abandoned and deprecated by the broader JavaScript/TypeScript ecosystem due to its lack of maintenance and outdated feature set. Using it in new projects is strongly discouraged, and existing projects should actively plan for migration. ↓

fix Transition your build pipeline to modern, actively maintained bundlers such as Webpack, Rollup, esbuild, or Parcel. These alternatives provide superior support, performance, and features for current development practices and future-proofing.

Install

npm install ts-bundle

yarn add ts-bundle

pnpm add ts-bundle

Imports

bundle
wrong
```
const { bundle } = require('ts-bundle');
```
correct
```
const bundle = require('ts-bundle');
```
The package exports the `bundle` function as its default module export in CommonJS, not as a named property. This is a common pattern for older CommonJS modules where the module itself is a function.
bundle (ESM)
wrong
```
import { bundle } from 'ts-bundle';
```
correct
```
import bundle from 'ts-bundle';
```
While the package is fundamentally a CommonJS module, this would be the correct syntax for ESM interop if used in an ESM project. However, direct native ESM support is unlikely due to the package's age.
IConfig
```
import type { IConfig } from 'ts-bundle';
```
This type definition is used for type checking the configuration object passed to the `bundle` function. It requires TypeScript to be installed in your project. Be aware that these type definitions may not be fully compatible with very modern TypeScript versions or syntax.

Quickstart

Bundles a TypeScript entry file (`src/main.ts`) into a single output (`dist/my-library.ts`), demonstrating configuration options like root module, license inclusion, and versioning.

const bundle = require("ts-bundle");

// A minimal example bundling a main TypeScript file
bundle({
    src: 'src/main.ts', // Specify your primary TypeScript entry file
    dest: ['dist/my-library.ts'], // Output bundle to one or more paths
    rootModule: 'MyProjectNamespace', // Optional: wrap output in a root module
    license: 'LICENSE.md', // Optional: path to a license file to prepend
    version: '2.0.0', // Optional: version to insert into license (e.g., v0.0.0 -> v2.0.0)
    disableLint: true // Optional: disable tslint comments in output
}, function (err) {
  if (err) {
    console.error('TypeScript bundling failed:', err);
    process.exit(1);
  } else {
    console.log('TypeScript bundle created successfully at dist/my-library.ts!');
  }
});