brk_bundler

Asset bundling and development server for BRK web interfaces with hot reloading and file watching.

Overview

This crate provides a thin wrapper around the Rolldown JavaScript bundler specifically designed for BRK web interface development. It handles asset bundling, file copying, template processing, and development-mode file watching with automatic rebuilds and hot reloading for efficient web development workflows.

Key Features:

• JavaScript bundling with Rolldown (Rust-based bundler)
• Automatic file watching and hot reloading in development mode
• Template processing with version injection and asset hash replacement
• Service worker generation with version management
• Source map generation for debugging
• Minification for production builds
• Async/await support with Tokio integration

Target Use Cases:

• BRK blockchain explorer web interfaces
• Development of Bitcoin analytics dashboards
• Building responsive web applications for blockchain data visualization
• Hot reloading development environment for rapid iteration

Installation

cargo add brk_bundler

Quick Start

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

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let websites_path = Path::new("./web");
    let source_folder = "src";
    let watch = true; // Enable hot reloading

    // Bundle assets and start development server
    let dist_path = bundle(websites_path, source_folder, watch).await?;

    println!("Assets bundled to: {}", dist_path.display());

    // Keep running for file watching (in watch mode)
    if watch {
        tokio::signal::ctrl_c().await?;
    }

    Ok(())
}

API Overview

Core Functions

bundle(websites_path: &Path, source_folder: &str, watch: bool) -> io::Result<PathBuf> Main bundling function that processes web assets and optionally starts file watching.

Bundling Process

1. Directory Setup: Creates dist/ directory and copies source files
2. JavaScript Bundling: Processes scripts/entry.js with Rolldown bundler
3. Template Processing: Updates index.html with hashed asset references
4. Service Worker: Generates service worker with version injection
5. File Watching: Optionally monitors source files for changes

Configuration

Rolldown Bundler Options:

• Input: ./src/scripts/entry.js (main JavaScript entry point)
• Output: ./dist/scripts/ directory
• Minification: Enabled for production builds
• Source Maps: File-based source maps for debugging
• Asset Hashing: Automatic hash generation for cache busting

Examples

Development Mode with Hot Reloading

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

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let web_root = Path::new("./websites");

    // Start development server with file watching
    let _dist_path = bundle(web_root, "explorer", true).await?;

    println!("Development server started!");
    println!("Hot reloading enabled - edit files to see changes");

    // Keep server running
    loop {
        tokio::time::sleep(tokio::time::Duration::from_secs(1)).await;
    }
}

Production Build

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

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let web_root = Path::new("./websites");

    // Build for production (no watching)
    let dist_path = bundle(web_root, "dashboard", false).await?;

    println!("Production build completed: {}", dist_path.display());

    // Assets are minified and ready for deployment
    Ok(())
}

Custom Web Application Structure

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

// Expected directory structure:
// websites/
// ├── my_app/
// │   ├── index.html          // Main HTML template
// │   ├── service-worker.js   // Service worker template
// │   ├── scripts/
// │   │   └── entry.js        // JavaScript entry point
// │   ├── styles/
// │   │   └── main.css        // CSS files
// │   └── assets/
// │       └── images/         // Static assets
// └── dist/                   // Generated output

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let websites_path = Path::new("./websites");
    let source_folder = "my_app";

    let dist_path = bundle(websites_path, source_folder, false).await?;

    // Result: dist/ contains bundled and processed files
    // - dist/index.html (with updated script references)
    // - dist/service-worker.js (with version injection)
    // - dist/scripts/main.[hash].js (minified and hashed)
    // - dist/styles/ (copied CSS files)
    // - dist/assets/ (copied static assets)

    Ok(())
}

Architecture

File Processing Pipeline

1. Source Copying: Recursively copies all source files to dist directory
2. JavaScript Bundling: Rolldown processes entry.js with dependencies
3. Asset Hashing: Generates content-based hashes for cache busting
4. Template Updates: Replaces placeholders in HTML templates
5. Version Injection: Updates service worker with current package version

File Watching System

Development Mode Watchers:

• Source File Watcher: Monitors non-script files for changes
• Bundle Watcher: Watches JavaScript files and triggers rebuilds
• Template Watcher: Updates HTML when bundled assets change

Event Handling:

• File Creation/Modification: Automatic copying to dist directory
• Script Changes: Triggers Rolldown rebuild and template update
• Template Changes: Processes HTML and updates asset references

Template Processing

index.html Processing:

• Scans bundled JavaScript for asset hash
• Replaces /scripts/main.js with /scripts/main.[hash].js
• Maintains cache busting while preserving template structure

service-worker.js Processing:

• Replaces __VERSION__ placeholder with current crate version
• Enables version-based cache invalidation
• Maintains service worker functionality

Async Architecture

Built on Tokio async runtime:

• Non-blocking I/O: Efficient file operations and watching
• Concurrent Tasks: Parallel file watching and bundle processing
• Background Processing: Development server runs in background task

Configuration Options

Rolldown Configuration

The bundler uses optimized Rolldown settings:

BundlerOptions {
    input: Some(vec!["./src/scripts/entry.js".into()]),
    dir: Some("./dist/scripts".to_string()),
    minify: Some(RawMinifyOptions::Bool(true)),
    sourcemap: Some(SourceMapType::File),
    // ... other default options
}

File Structure Requirements

Required Files:

• src/scripts/entry.js - JavaScript entry point
• src/index.html - HTML template
• src/service-worker.js - Service worker template

Optional Directories:

• src/styles/ - CSS stylesheets
• src/assets/ - Static assets (images, fonts, etc.)
• src/components/ - Additional JavaScript modules

Development Workflow

Setup

1. Create web application in websites/app_name/
2. Add required files (index.html, entry.js, service-worker.js)
3. Run bundler in watch mode for development

Hot Reloading

• Script Changes: Automatic bundle rebuild and browser refresh
• Template Changes: Immediate HTML update with asset hash replacement
• Asset Changes: Instant copy to dist directory
• Style Changes: Direct copy without bundling

Production Deployment

1. Run bundler without watch mode
2. Deploy dist/ directory contents
3. Assets include content hashes for cache busting
4. Service worker includes version for cache management

Code Analysis Summary

Main Function: bundle() async function coordinating Rolldown bundler with file processing and watching
File Operations: Recursive directory copying with copy_dir_all() and selective file processing
Templating: String replacement for asset hash injection and version management
File Watching: Multi-watcher system using notify crate for real-time development feedback
Async Integration: Tokio-based async architecture with background task spawning
Bundler Integration: Rolldown wrapper with optimized configuration for web development
Architecture: Development-focused asset pipeline with hot reloading and production optimization

This README was generated by Claude Code