# @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

## 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](https://lossless.link/contribute-onetime) or [contribute monthly](https://lossless.link/contribute). :)

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

> MIT licensed | **&copy;** [Lossless GmbH](https://lossless.gmbh)
| By using this npm module you agree to our [privacy policy](https://lossless.gmbH/privacy)

[![repo-footer](https://lossless.gitlab.io/publicrelations/repofooter.svg)](https://maintainedby.lossless.com)