Lux Quickstart Guide

Get from zero to running Lux code in 5 minutes.

Install

# From the joulesperbit workspace — builds the `lux` binary:
cargo build --release -p lux-cli

# The canonical formatter is a separate binary:
cargo build --release -p lux-fmt

# Add both to PATH:
export PATH="$PWD/target/release:$PATH"

# Verify:
lux version
# → Lux v0.1.0

Hello World

Create hello.lux:

fn main():
    print("Hello, world!")

Run it:

lux run hello.lux
# → Hello, world!
# Energy: 0.0023 J | 847 ops | 0.12 W

Every execution produces an energy receipt — joules consumed, operations counted, watts drawn.

Create a Project

lux new my-app
cd my-app

This creates:

my-app/
├── joule.toml      # Project manifest
├── src/
│   └── main.lux    # Entry point
└── tests/
    └── main_test.lux

joule.toml

[project]
name = "my-app"
version = "0.1.0"
entry = "src/main.lux"

[build]
target = "native"  # or "wasm"

Language Basics

Variables and Types

let name = "Lux"              # Inferred as str
let mut count = 0              # Mutable integer
let ratio: float = 3.14        # Explicit type
let items: [int] = [1, 2, 3]  # Typed list

Functions

fn greet(name: str) -> str:
    "hello {name}"

fn add(a: int, b: int) -> int = a + b  # Expression body

Control Flow

if score > 90:
    print("excellent")
else:
    print("keep going")

for item in items:
    print(item)

match status:
    "ok" => handle_ok()
    "error" => handle_error()
    _ => handle_unknown()

Apps (Full-stack UI)

app Counter:
    let mut count = signal(0)

    view:
        h1 "Counter: {count}"
        button @click={count += 1} "+"
        button @click={count -= 1} "-"

Servers

server Api port=8080:
    get "/health":
        respond {status: "ok"}

    post "/echo":
        let body = request.body
        respond body

Styles

style card:
    background = "#fff"
    padding = "16px"
    border_radius = "8px"
    box_shadow = "0 2px 4px rgba(0,0,0,0.1)"

Pattern Matching

fn describe(value):
    match value:
        0 => "zero"
        1..10 => "small"
        n if n > 100 => "large: {n}"
        _ => "other"

Pipe Operator

let result = data
    |> filter(x => x > 0)
    |> map(x => x * 2)
    |> sum()

CLI Commands

Formatting is a separate binary, lux-fmt (not a lux fmt subcommand): lux-fmt [files...] formats in place; --check verifies; --stdin reads stdin → stdout; lux-fmt . recurses.

Energy Auditing (No Migration Required)

Audit existing code without converting anything:

# Audit a JavaScript project
lux audit ./my-js-app

# JSON output for CI pipelines
lux audit ./src --format json

# Only critical issues
lux audit . --severity critical

Output:

Energy Audit Report
═══════════════════
Files scanned: 47
Languages: JavaScript (32), TypeScript (12), Python (3)

CRITICAL  N+1 query in loop         src/api/users.js:42      ~100x waste
HIGH      O(n²) nested loop         src/utils/sort.js:18     ~10x waste
MEDIUM    String concat in loop     src/render.js:95         ~5x waste

Standard Library

Lux ships 1,723 modules — no package manager needed for common tasks:

use lux:http          # HTTP client/server
use lux:json          # JSON parse/serialize
use lux:crypto        # Hashing, encryption
use lux:chart         # Data visualization
use lux:math          # Math functions
use lux:regex         # Regular expressions
use lux:websocket     # WebSocket client/server
use lux:test          # Testing framework

Run lux list to see all available modules.

Editor Setup

VSCode

1. Build the LSP: cargo build --release -p lux-lsp
2. Point your editor’s Lux extension at the lux-lsp binary.
3. Reload the editor.

Features: diagnostics (parse-on-change), completion (keywords, types, modules, builtins), hover docs, go-to-definition.

MCP (AI Integration)

cargo build --release -p lux-mcp

Add to your MCP client config (Claude Code, Cursor, etc.):

{
    "mcpServers": {
        "lux": {
            "command": "/path/to/lux-mcp"
        }
    }
}

Tools available: lux_run, lux_check, lux_audit, lux_lift, lux_modules, lux_docs.

Testing

test "addition works":
    assert add(2, 3) == 5

test "greeting includes name":
    let result = greet("Lux")
    assert result == "hello Lux"

lux test
# ✓ addition works (0.0001 J)
# ✓ greeting includes name (0.0001 J)
# 2 tests passed | 0.0002 J total

What’s Next

• Read the full Language Specification
• Read the Whitepaper on energy-efficient computing
• Browse the standard library modules (1,723 modules)
• Try lux audit on your existing codebase — no commitment required

Lux v0.1.0 — Open Interface Engineering, Inc. — March 2026