Crate heisenberg 

Heisenberg

Framework-agnostic dual-mode web serving for Rust applications.

Heisenberg provides seamless switching between proxy mode (forwarding to frontend dev servers) and embed mode (serving embedded static assets) without being opinionated about your web framework.

Quick Start

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

#[tokio::main]
async fn main() {
    let spa = heisenberg::embed_spa!("./web/build");
    let config = Heisenberg::new()
        .route("/*", spa)
        .dev_server("http://localhost:5173")
        .build();

    let app = Router::new()
        .route("/api/hello", get(|| async { "Hello API!" }))
        .layer(HeisenbergLayer::new(config));

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

Features

• Framework Agnostic: Works with any Tower-based framework (Axum, Warp, Hyper)
• Dual Mode: Automatic proxy/embed mode switching
• Smart Inference: Automatically detects frontend configuration from package.json
• Process Management: Handles frontend dev server lifecycle
• SPA Support: Client-side routing with fallback to index.html
• Optional Logging: Structured diagnostics with tracing (enable logging feature)

Mode Detection

• Proxy Mode: cargo run → Forward to frontend dev server
• Embed Mode: cargo build --release → Serve embedded assets
• Override: HEISENBERG_MODE=embed|proxy environment variable

Re-exports

pub use crate::core::config::Heisenberg;

pub use crate::core::config::SpaRouteBuilder;

pub use crate::core::embedded_spa::EmbeddedSpa;

pub use crate::error::HeisenbergError;

pub use crate::utils::shutdown_signal;

pub use crate::tower::HeisenbergLayer;

pub use crate::tower::HeisenbergService;

Modules

config

Configuration file support

core

Core Heisenberg functionality

error

Error types for Heisenberg

services

Service implementations for Heisenberg

tower

Tower integration for Heisenberg

utils

Utility functions for Heisenberg

Macros

embed_spa