git.zone/tsbundle

Fork 0

Files

Juergen Kunz 82c7bb3ee1 fix(readme): Update license and legal information section in readme

2025-06-26 20:09:58 +00:00

8.5 KiB

Raw Blame History

@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

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

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.

8.5 KiB Raw Blame History