# @git.zone/tsbundle

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

## Installation

```bash
# 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:

```bash
# 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

```typescript
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:

```bash
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:

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

#### `tsbundle npm`

Bundle npm packages for distribution:

```bash
tsbundle npm
# Prepares your package for npm publishing
```

#### `tsbundle website`

Full website bundling with HTML processing and asset handling:

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

## API Reference

### TsBundle Class

The main bundler class for programmatic usage.

```typescript
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

```typescript
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:

```typescript
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.):

```typescript
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

```typescript
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

```typescript
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

```typescript
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:

```json
{
  "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

## 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](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.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.