@git.zone/tsbundle

A powerful multi-bundler tool supporting esbuild, rolldown, and rspack for painless bundling of web projects.

Installation

# Global installation for CLI usage
npm install -g @git.zone/tsbundle

# Local installation for project usage
npm install --save-dev @git.zone/tsbundle

Quick Start

CLI Usage

The simplest way to bundle your project:

# Bundle with default settings (from ./ts_web/index.ts to ./dist_bundle/bundle.js)
tsbundle

# Bundle with custom paths
tsbundle --from="./src/index.ts" --to="./dist/bundle.js"

# Production build with minification
tsbundle --from="./src/index.ts" --to="./dist/bundle.js" --production

# Use a specific bundler
tsbundle --bundler=rolldown

API Usage

import { TsBundle } from '@git.zone/tsbundle';

const bundler = new TsBundle();

// Basic usage
await bundler.build(
  process.cwd(),                    // working directory
  './src/index.ts',                 // entry point
  './dist/bundle.js',               // output file
  { bundler: 'esbuild' }            // options
);

// Production build with rolldown
await bundler.build(
  process.cwd(),
  './src/index.ts',
  './dist/bundle.min.js',
  { 
    bundler: 'rolldown',
    production: true 
  }
);

Available Bundlers

tsbundle supports three modern bundlers, each with its own strengths:

• esbuild (default): Extremely fast, great for development
• rolldown: Rust-based bundler with excellent tree-shaking
• rspack: High-performance bundler with webpack compatibility

Select your bundler using the --bundler flag in CLI or the bundler option in API.

CLI Commands

Default Command

Bundle TypeScript/JavaScript projects:

tsbundle [options]

Options:
  --from          Source entry point (default: ./ts_web/index.ts)
  --to            Output bundle path (default: ./dist_bundle/bundle.js)
  --production    Enable production mode with minification
  --bundler       Choose bundler: esbuild, rolldown, or rspack
  --commonjs      Output CommonJS format instead of ESM
  --skiplibcheck  Skip TypeScript library checking

Specialized Commands

tsbundle element

Bundle web components with standard naming conventions:

tsbundle element
# Bundles from ./ts_web/elements/<elementName>.ts to ./dist_bundle/bundle.js

tsbundle npm

Bundle npm packages for distribution:

tsbundle npm
# Prepares your package for npm publishing

tsbundle website

Full website bundling with HTML processing and asset handling:

tsbundle website
# Bundles JavaScript, processes HTML, and copies assets

API Reference

TsBundle Class

The main bundler class for programmatic usage.

import { TsBundle } from '@git.zone/tsbundle';

const bundler = new TsBundle();

// Method signature
await bundler.build(
  cwdArg: string,                              // Working directory
  fromArg?: string,                            // Entry point (default: './ts_web/index.ts')
  toArg?: string,                              // Output path (default: './dist_bundle/bundle.js')
  argvArg?: ICliOptions                        // Configuration options
): Promise<void>

ICliOptions Interface

interface ICliOptions {
  bundler: 'esbuild' | 'rolldown' | 'rspack'; // Bundler to use
  production?: boolean;                         // Enable production optimizations
  commonjs?: boolean;                          // Output CommonJS format
  skiplibcheck?: boolean;                      // Skip TypeScript lib checking
}

HtmlHandler Class

Process and minify HTML files:

import { HtmlHandler } from '@git.zone/tsbundle';

const htmlHandler = new HtmlHandler();

// Check if HTML files exist
const exists = await htmlHandler.checkIfExists();

// Process HTML with options
await htmlHandler.processHtml({
  from: './src/index.html',    // Source HTML (default: './html/index.html')
  to: './dist/index.html',     // Output HTML (default: './dist_serve/index.html')
  minify: true                 // Enable minification
});

AssetsHandler Class

Handle static assets (images, fonts, etc.):

import { AssetsHandler } from '@git.zone/tsbundle';

const assetsHandler = new AssetsHandler();

// Ensure assets directory exists
await assetsHandler.ensureAssetsDir();

// Copy and process assets
await assetsHandler.processAssets({
  from: './src/assets',        // Source directory (default: './assets')
  to: './dist/assets'          // Output directory (default: './dist_serve/assets')
});

Advanced Examples

Building a Modern Web Application

import { TsBundle, HtmlHandler, AssetsHandler } from '@git.zone/tsbundle';

async function buildWebApp() {
  const bundler = new TsBundle();
  const htmlHandler = new HtmlHandler();
  const assetsHandler = new AssetsHandler();
  
  // Bundle the JavaScript
  await bundler.build(
    process.cwd(),
    './src/app.ts',
    './dist/app.js',
    { 
      bundler: 'rolldown',
      production: true 
    }
  );
  
  // Process HTML
  await htmlHandler.processHtml({
    from: './src/index.html',
    to: './dist/index.html',
    minify: true
  });
  
  // Copy assets
  await assetsHandler.processAssets({
    from: './src/assets',
    to: './dist/assets'
  });
  
  console.log('Build complete!');
}

buildWebApp();

Multi-Entry Point Bundling

import { TsBundle } from '@git.zone/tsbundle';

async function buildMultipleEntries() {
  const bundler = new TsBundle();
  const entries = [
    { from: './src/main.ts', to: './dist/main.js' },
    { from: './src/admin.ts', to: './dist/admin.js' },
    { from: './src/worker.ts', to: './dist/worker.js' }
  ];
  
  for (const entry of entries) {
    await bundler.build(
      process.cwd(),
      entry.from,
      entry.to,
      { bundler: 'esbuild' }
    );
  }
}

Development vs Production Builds

import { TsBundle } from '@git.zone/tsbundle';

const bundler = new TsBundle();
const isDev = process.env.NODE_ENV === 'development';

await bundler.build(
  process.cwd(),
  './src/index.ts',
  isDev ? './dist/dev/bundle.js' : './dist/prod/bundle.min.js',
  { 
    bundler: isDev ? 'esbuild' : 'rolldown',  // esbuild for speed in dev
    production: !isDev,                        // minify in production
    commonjs: false                            // use ES modules
  }
);

TypeScript Configuration

tsbundle works best with the following TypeScript configuration:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true
  }
}

Best Practices

1. Entry Points: Keep your entry points in ts_web/ for web bundles or ts/ for library bundles
2. Output Structure: Use dist_bundle/ for bundled files and dist_serve/ for web-ready files
3. Bundler Selection:
   • Use esbuild for development (fastest)
   • Use rolldown or rspack for production (better optimization)
4. Assets: Place static assets in the assets/ directory
5. HTML: Keep HTML templates in the html/ directory

Contribution

We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can contribute one time or contribute monthly. :)

For further information read the linked docs at the top of this readme.

MIT licensed | © Lossless GmbH | By using this npm module you agree to our privacy policy