brk_bundler provides JavaScript/TypeScript bundling capabilities for BRK's web interfaces. It's a thin wrapper around Rolldown (Rust-based Rollup alternative) with BRK-specific configuration for building optimized web assets with file watching and automatic rebuilding.

What it provides

JavaScript Bundling: Modern ES modules bundling with minification
File Watching: Automatic rebuilding on source file changes
Asset Processing: Copies and processes static assets
Version Injection: Automatic version string replacement in service workers
Development Mode: Live rebuilding for rapid development

Key Features

Bundling Capabilities

ES Module Support: Modern JavaScript bundling with tree-shaking
Minification: Automatic code minification for production builds
Source Maps: Generated source maps for debugging
Entry Point Processing: Configurable entry points with hashed output names

File System Operations

Directory Copying: Copies entire source directories to distribution
Selective Processing: Special handling for specific file types
Path Resolution: Automatic path resolution and asset linking

Development Features

Hot Rebuilding: Automatic rebuilds on file changes
Watch Mode: Monitors source files and triggers rebuilds
Version Replacement: Injects build version into service workers

Usage

Basic Bundling

use brk_bundler::bundle;
use std::path::Path;

// Bundle without watching (production)
let websites_path = Path::new("./websites");
let source_folder = "default";
let dist_path = bundle(websites_path, source_folder, false).await?;

println!("Bundled to: {:?}", dist_path);

Development Mode with Watching

// Bundle with file watching (development)
let dist_path = bundle(websites_path, "default", true).await?;

// Bundler now watches for changes and rebuilds automatically
// This will run in the background until the process exits

Integration with BRK CLI

// Typically called from brk_cli when serving websites
async fn setup_website(config: &Config) -> Result<PathBuf> {
    let websites_path = config.websites_path();
    let source_folder = match config.website_mode {
        WebsiteMode::Default => "default",
        WebsiteMode::Custom => "custom",
        WebsiteMode::None => return Ok(PathBuf::new()),
    };
    
    // Bundle the website assets
    let dist_path = bundle(websites_path, source_folder, config.dev_mode).await?;
    
    Ok(dist_path)
}

File Structure

The bundler expects this directory structure:

websites/
├── default/                 # Default website source
│   ├── index.html          # Main HTML file
│   ├── service-worker.js   # Service worker (version injected)
│   ├── scripts/            # JavaScript/TypeScript source
│   │   ├── entry.js        # Main entry point
│   │   ├── main.js         # Application logic
│   │   └── ...             # Other JS modules
│   └── assets/             # Static assets
└── dist/                   # Generated output directory
    ├── index.html          # Processed HTML with updated script references
    ├── service-worker.js   # Service worker with version injected
    ├── scripts/            # Bundled and minified JavaScript
    │   └── main-[hash].js  # Hashed output file
    └── assets/             # Copied static assets

Bundling Process

Clean: Removes existing dist/ directory
Copy: Copies all source files to dist/
Bundle JavaScript:
- Processes scripts/entry.js as entry point
- Generates minified bundle with source maps
- Creates hashed filename for cache busting
Process HTML: Updates script references to hashed filenames
Process Service Worker: Injects current version string
Watch (if enabled): Monitors for file changes and rebuilds

Configuration

The bundler uses Rolldown with these optimized settings:

BundlerOptions {
    input: Some(vec![source_entry.into()]),    // scripts/entry.js
    dir: Some("./dist/scripts".to_string()),   // Output directory
    cwd: Some(websites_path),                  // Working directory
    minify: Some(RawMinifyOptions::Bool(true)), // Enable minification
    sourcemap: Some(SourceMapType::File),      // Generate source maps
    ..Default::default()
}

File Watching

In watch mode, the bundler monitors:

Source files: Non-script files are copied on change
JavaScript files: Trigger full rebuild via Rolldown watcher
HTML files: Processed to update script references
Service worker: Version injection on changes

Watch Events Handled

Create - New files added
Modify - Existing files changed
Ignores Delete and other events

Version Injection

Service workers get automatic version injection:

// In source service-worker.js
const VERSION = '__VERSION__';

// After bundling
const VERSION = 'v0.0.88';

This enables proper cache invalidation across releases.

Performance Features

Async Operations: All bundling operations are async
Incremental Builds: Only rebuilds changed files in watch mode
Parallel Processing: Uses Tokio for concurrent file operations
Efficient Copying: Direct file system operations

Error Handling

Graceful Failures: Logs errors but continues watching
Path Resolution: Automatic path absolutization and validation
File System Errors: Proper error propagation with context

Dependencies

brk_rolldown - Rust-based Rollup bundler
notify - File system watching
tokio - Async runtime for file operations
sugar_path - Path manipulation utilities
log - Error logging

Integration Points

The bundler integrates with:

brk_cli: Called during website setup
brk_server: Serves bundled assets
Development workflow: Provides live rebuilding

This README was generated by Claude Code