Heisenberg

Framework-agnostic dual-mode web serving for Rust applications. Seamlessly switch between development mode (proxying to frontend dev servers) and production mode (serving embedded static assets).

✨ Features

• 🔄 Dual Mode: Automatic dev/prod mode switching
• 🎯 Framework Agnostic: Works with Axum, Warp, Actix-web, Rocket, and more
• 🧠 Smart Inference: Auto-detects frontend configuration from package.json
• ⚡ Zero Config: Works out-of-the-box with sensible defaults
• 🔧 Process Management: Handles frontend dev server lifecycle
• 📱 SPA Support: Client-side routing with fallback to index.html
• 📊 Optional Logging: Structured diagnostics with tracing

🚀 Quick Start

1. Add to your Cargo.toml

[dependencies]
heisenberg = "0.1"
axum = "0.7"
tokio = { version = "1.35", features = ["full"] }

2. Basic setup

use axum::{routing::get, Router};
use heisenberg::Heisenberg;

#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/api/hello", get(|| async { "Hello API!" }))
        .layer(Heisenberg::new().spa("./dist"));

    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

3. Run in different modes

# Development mode - proxies to frontend dev server
cargo run

# Production mode - serves embedded assets  
cargo build --release && ./target/release/your-app

That's it! Heisenberg automatically:

• 🔍 Finds your package.json and extracts the dev command
• 🚀 Starts your frontend dev server (npm run dev)
• 🔗 Proxies frontend requests in development
• 📦 Embeds assets for production builds
• 🌐 Opens your browser automatically

📖 Documentation

• User Guide - Comprehensive setup and configuration guide
• API Documentation - Complete API reference
• Examples - Working examples for different frameworks

🎯 Framework Support

Tower-based (Zero Config)

Works automatically with any Tower-based framework:

// Axum
let app = Router::new().layer(heisenberg_config);

// Warp  
let routes = routes.with(heisenberg_config);

Framework Adapters

Helper functions for non-Tower frameworks:

// Actix-web
use heisenberg::actix::serve_spa;

// Rocket
use heisenberg::rocket::serve_spa;

⚙️ Configuration

Smart Defaults

// Infers everything from your project structure
Heisenberg::new().spa("./dist")

Advanced Configuration

Heisenberg::new()
    .spa("./frontend/dist")
        .dev_server("http://localhost:3000")
        .dev_command(["npm", "run", "dev"])
        .open_browser(true)
    .build()

Multiple SPAs

Heisenberg::new()
    .spa("/admin/*", "./admin/dist")
        .dev_server("http://localhost:3001")
    .spa("/*", "./app/dist")
        .dev_server("http://localhost:3000")
    .build()

🔧 Mode Detection

📊 Debugging

Enable structured logging:

[dependencies]
heisenberg = { version = "0.1", features = ["logging"] }
tracing-subscriber = "0.3"

RUST_LOG=debug,heisenberg=trace cargo run

🏗️ Examples

• Basic Axum - Simple Axum + React setup
• Logging - Structured logging example
• Multi-SPA - Multiple frontend applications
• Actix-web - Actix-web integration
• Rocket - Rocket integration

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.