About

Volt is a purpose-built, statically typed programming language designed from the ground up for the next generation of high-performance web applications.

Historically, web developers have faced a fundamental compromise:

1. JavaScript UI Frameworks (React, Vue, Angular) offer declarative syntax and great developer ergonomics, but pay a heavy price: tens of kilobytes of runtime bundle overhead, expensive Virtual DOM allocations and reconciliation passes, and noticeable hydration delays on resource-constrained devices.
2. Traditional WebAssembly (Rust, C++, Go) provides raw execution speed, but compiling to linear WebAssembly memory requires shipping an entire custom memory allocator or garbage collector in the binary (resulting in 50 KB – 2 MB+ binaries for simple components) plus complex serialization overhead across the JavaScript/Wasm bridge.

Volt's Core Purpose

Volt eliminates this tradeoff by targeting standard WebAssembly Garbage Collection (Wasm-GC). By leveraging the host browser's native garbage collector and compiling declarative UI definitions directly into deterministic, bitmask-driven reactive dispatch tables, Volt delivers:

• Bare-Metal Compilation Speed: Your reactive logic and DOM interaction compile directly into native Wasm-GC bytecode.
• Microscopic Binary Size: Standard interactive components compile to ~1.1 KB uncompressed, completely eliminating runtime bloat.
• Zero Virtual DOM & Zero Hydration: Signals compile directly to targeted host DOM updates (dom.setTextContent), making updates $O(1)$ without any tree diffing.
• Instant Mount Times: Components initialize and mount in under 1.5 milliseconds directly from streaming bytecode.

Why Volt?

Overview

Volt (.vt) is a statically typed, expression-oriented language targeting WebAssembly Garbage-Collected (Wasm-GC) binary modules. It eliminates JavaScript hydration taxes and Virtual DOM overhead through direct host pointer bindings and fine-grained reactive update dispatch.

• Zero Virtual DOM: Directly emits targeted DOM element creation and memory-mapped signal updates (dom.setTextContent) with zero VDOM diffing or reconciliation passes.
• Wasm-GC Native: Implements native Wasm-GC structs (struct.new, struct.get, struct.set) managed seamlessly by host browser garbage collection.
• Micro Binary Footprint: Minimal overhead compiler output yielding compact binaries (Counter components compile to ~1.1 KB uncompressed).
• Sub-Millisecond Mount Times: Direct linear DOM creation completes initial mount in 0.20 ms – 1.48 ms.
• First-Class TypeScript Interop: Automatically generates .d.ts declaration files for compiled Wasm modules and supports type-safe extern "js" host function imports.
• Zero-Dependency Micro-Bootloader: Standalone <volt-app src="..."> custom element runtime under 1.5 KB (boot.js).
• Deterministic Reactive Graph: Signal dependencies and computed expressions are resolved ahead-of-time (AOT) into bitmask dispatch tables, ensuring $O(1)$ signal update propagation.

Architecture

Volt compiles high-level .vt declarative component definitions directly into standard WebAssembly GC bytecode via an ahead-of-time reactivity planning engine:

flowchart TD
    Source[".vt Source File"] --> Lexer["Lexer / Tokenizer"]
    Lexer --> Parser["Recursive Descent Parser"]
    Parser --> AST["Abstract Syntax Tree (AST)"]
    
    subgraph Analysis["Reactivity & Dependency Analysis"]
        AST --> ReactivePlan["AOT Reactivity Analyzer"]
        ReactivePlan --> SignalGraph["Signal Dependency Bitmasks"]
        ReactivePlan --> DynamicSlots["Dynamic Text / Attr Slots"]
        ReactivePlan --> ElementPlan["Linear DOM Creation Plan"]
    end
    
    subgraph Codegen["Wasm-GC Binary Emission"]
        SignalGraph --> WasmCompiler["Wasm-GC Bytecode Compiler"]
        DynamicSlots --> WasmCompiler
        ElementPlan --> WasmCompiler
        WasmCompiler --> WasmBinary[".wasm Binary (GC Structs + Dispatch Table)"]
        WasmCompiler --> DtsEmitter[".d.ts TypeScript Declarations"]
    end
    
    subgraph Runtime["Browser Host Execution (< 1.5 KB Bootloader)"]
        WasmBinary --> HostDOM["Direct DOM Updates (externref + dom.setTextNumber)"]
    end

Reactivity Model

Every signal in a Volt component is mapped to a dedicated struct field in Wasm-GC memory with a corresponding bitmask flag:

$$\text{Dirty Mask} = \bigvee_{i \in \text{Modified}} (1 \ll \text{Signal ID}_i)$$

When an action mutates a signal, the component updates the struct field, applies bitwise masking across computed expressions and dynamic DOM text slots, and triggers surgical updates to the host DOM with zero tree walking.

Language Specification

Volt combines clean, concise syntax with explicit reactivity declarations:

extern "js" {
  fn logMetric(event: string, value: i32);
}

export component Counter {
  signal count: i32 = 0;
  signal step: i32 = 1;

  computed doubled: i32 = count * 2;

  fn increment() {
    count += step;
    logMetric("count_updated", count);
  }

  fn reset() {
    count = 0;
  }

  render {
    <div class="counter-card">
      <h2>"Volt Reactive Counter"</h2>
      <p>"Current Value: " {count} " (Doubled: " {doubled} ")" </p>
      <div class="actions">
        <button @click=increment>"Increment"</button>
        <button @click=reset>"Reset"</button>
      </div>
    </div>
  }
}

Key Language Primitives

• signal <name>: <type> = <expr>;: Reactive state primitive mapped directly to Wasm-GC struct fields.
• computed <name>: <type> = <expr>;: Pure derived expression recalculated only when upstream signal bitmasks trip.
• extern "js" { ... }: Type-safe FFI interface allowing Volt components to call host JavaScript functions and browser APIs.
• fn <name>(<args>) { ... }: Component methods exposed to host DOM event listeners via WebAssembly Table funcref indices.
• render { <jsx> }: Declarative DOM structure compiled into a linear sequence of host DOM allocations and static text nodes.

Getting Started

Prerequisites

• Rust 1.80+ (with cargo)
• Modern Browser with Wasm-GC enabled (Chrome 119+, Firefox 120+, Safari 18+)

Installation & Build

Clone the repository and build the release binary:

git clone https://github.com/bshea-1/volt.git
cd volt
cargo build --release

The compiled binary is available at ./target/release/volt.

Quick Start

1. Compile a Component

Compile a .vt file into a WebAssembly GC module with companion TypeScript declarations:

volt build component.vt -o component.wasm --dts component.d.ts

2. Validate Component Syntax

Verify syntax, signal graphs, dynamic text slots, and reactive dependencies without emitting bytecode:

volt check component.vt

3. Embed in HTML

Mount the compiled component into any web page using the Volt micro-bootloader:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Volt App</title>
</head>
<body>
  <!-- Declarative Volt Web Component -->
  <volt-app src="./component.wasm"></volt-app>

  <!-- Lightweight Micro-Bootloader (< 1.5 KB) -->
  <script type="module" src="./boot.js"></script>
</body>
</html>

4. Serve Locally

Start a development server with native WebAssembly MIME configurations:

volt serve --port 3000 --dir examples

Comparison

CLI Reference

Volt: High-Performance, Reactive Web Language Targeting Wasm-GC

Usage: volt <COMMAND>

Commands:
  build  Compile a .vt source file into a Wasm-GC module (.wasm)
  check  Parse and validate a .vt source file
  serve  Serve an interactive development directory with Wasm-GC support
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

FAQ

License

MIT License. Copyright (c) 2026 bshea-1.

See LICENSE for full details.