Getting Started

Pax is a UI framework for Rust, with targets for web, macOS, iOS, and iPadOS. Start with pax-cli and the web target on macOS, Linux, or Windows. This gives every workstation the same first project, development server, and template reload workflow. Native Apple targets are an optional next step and require a macOS workstation with full Xcode.

Quick start

Install Rust and your workstation's web prerequisites, then run:

cargo install pax-cli
pax-cli create my-first-project
cd my-first-project
pax-cli run --target web

Open the local URL printed by the last command. The CLI builds, packages, and serves the application. Installing the CLI compiles the development tools once; the first project build also compiles its dependencies. Your application needs no build.rs or Cargo runner configuration. .pax edits reload in the running session; Rust changes require rebuilding and restarting.

Choose a web port or see the available development options:

pax-cli run --target web --port 8080
pax-cli run --help

Web development does not build the Apple SDK. Once the browser app is running, you can run it natively on macOS or try an iOS simulator.

The CLI's telemetry policy is described in CLI Telemetry. Ordinary Cargo compilation and direct native execution do not invoke it.

Need the prerequisites? Start with Prepare your workstation. Already running? Continue to Project anatomy.

Prepare your workstation

You can develop Pax web applications on macOS, Debian/Ubuntu Linux, or Windows. Native macOS, iOS, and iPadOS development requires a macOS workstation with full Xcode. Native Linux and Windows applications are not supported yet; use the web target on those workstations.

Choose the instructions for your workstation below. If Rust is already installed, you can skip its installation commands. The WebAssembly target and wasm-pack are needed only for web builds.

macOS

For web development, Apple's Command Line Tools are sufficient. Install them if needed:

xcode-select --install

Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"

Install the web tools:

rustup target add wasm32-unknown-unknown
cargo install wasm-pack --version 0.15.0

Native Apple development additionally requires full Xcode and its first-launch setup. See Apple preparation when you are ready to use a native target.

Continue to Install the Pax CLI.

Linux (Debian / Ubuntu)

Install the system packages, Rust, and the web build tools:

# Install native build dependencies.
sudo apt update
sudo apt install -y \
  ca-certificates curl git build-essential pkg-config libssl-dev \
  python3 unzip xvfb \
  libglib2.0-dev libcairo2-dev libpango1.0-dev

# Install Rust.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. "$HOME/.cargo/env"

# Install the WebAssembly target and helper.
rustup target add wasm32-unknown-unknown
cargo install wasm-pack --version 0.15.0

Continue to Install the Pax CLI.

Windows

Install Visual Studio Build Tools with the C++ workload, Git, Rust, and the web build tools from PowerShell. The setup below also installs Clang for dependencies that need it on ARM64 Windows. It uses winget to install Git and may prompt for administrator approval.

Windows setup commands

Run these commands in order in the same PowerShell session:

# Install Visual Studio Build Tools.
$installer = "$env:TEMP\vs_BuildTools.exe"
Invoke-WebRequest https://aka.ms/vs/17/release/vs_BuildTools.exe -OutFile $installer
$vsArgs = @(
  "--quiet",
  "--wait",
  "--norestart",
  "--installPath", "C:\BuildTools",
  "--add", "Microsoft.VisualStudio.Workload.VCTools",
  "--add", "Microsoft.VisualStudio.Component.VC.Llvm.Clang",
  "--add", "Microsoft.VisualStudio.Component.VC.Llvm.ClangToolset",
  "--includeRecommended"
)

if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") {
  $vsArgs += @("--add", "Microsoft.VisualStudio.Component.VC.Tools.ARM64")
}

Start-Process $installer -Wait -ArgumentList $vsArgs

# Load the MSVC environment in this shell.
$vcvars = "C:\BuildTools\VC\Auxiliary\Build\vcvarsall.bat"
$vcArch = if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { "arm64" } else { "x64" }
cmd.exe /s /c "`"$vcvars`" $vcArch >nul && set" | ForEach-Object {
  $separator = $_.IndexOf("=")
  if ($separator -gt 0) {
    Set-Item -Path "Env:$($_.Substring(0, $separator))" `
      -Value $_.Substring($separator + 1)
  }
}

# Make Git and clang available to future shells.
winget install --id Git.Git --exact --source winget `
  --accept-package-agreements --accept-source-agreements

$llvmPath = "C:\BuildTools\VC\Tools\Llvm\bin"
$userPath = @(
  [Environment]::GetEnvironmentVariable("Path", "User") -split ";" |
    Where-Object { $_ }
)
foreach ($path in @("C:\Program Files\Git\cmd", $llvmPath)) {
  if ($userPath -notcontains $path) {
    $userPath = @($userPath) + $path
  }
}
[Environment]::SetEnvironmentVariable("Path", ($userPath -join ";"), "User")
$env:Path = "C:\Program Files\Git\cmd;$llvmPath;$env:Path"

# Install Rust.
$rustupArch = if ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") {
  "aarch64-pc-windows-msvc"
} else {
  "x86_64-pc-windows-msvc"
}

$rustup = "$env:TEMP\rustup-init.exe"
Invoke-WebRequest "https://static.rust-lang.org/rustup/dist/$rustupArch/rustup-init.exe" -OutFile $rustup
& $rustup -y --profile default --default-toolchain stable
$env:Path = "$env:USERPROFILE\.cargo\bin;$env:Path"

# Install the WebAssembly target and helper.
rustup target add wasm32-unknown-unknown
cargo install wasm-pack --version 0.15.0

Continue in the same PowerShell session to Install the Pax CLI.

Install the Pax CLI

Cargo is Rust's package manager. Use it to install the published Pax CLI:

cargo install pax-cli
pax-cli --version

The version command confirms that your shell can find the installed CLI. Installing it compiles Pax and its dependencies, so expect compilation output before the command finishes.

If you completed the Quick Start, continue to Project anatomy.

Create a project

From the directory where you keep your projects, run:

pax-cli create my-first-project

Choose a destination that does not already exist. The CLI creates Pax Logo: a small scene with an animation-position slider, Replay, and a light/dark background toggle. Its three source files contain the scene, controls, and native entry point. The logo itself comes from pax-std, re-exported by pax_kit; its geometry and animation sources stay out of your project. The starter is bundled with your CLI version; no repository checkout is needed.

For a smaller starting point, use pax-cli create my-counter --example=increment. The curated alternatives and their purpose are covered in Developer Workflow.

Run it on the web

Enter the project directory and start the web target:

cd my-first-project
pax-cli run --target web

The first run builds your application and its dependencies. Once the server is ready, the terminal prints a local URL beginning with http://127.0.0.1:. Open that URL in your browser. Use the address from your current run, since the port can change between sessions.

Your first-run checkpoint is the animated Pax logo. Drag the slider to choose an animation position; click Replay or the logo to play it again. The button at the top switches between light and dark backgrounds. A blank page or a build error means there's still something to resolve; see When something goes wrong.

Leave the command running while you use the app. To stop the development session, press Ctrl-C in its terminal. You can start it again with pax-cli run --target web from the project directory.

Run it natively on macOS

Enter the project directory and start a native development session:

cd my-first-project
pax-cli run --target macos

The window displays the same logo scene and controls. Drag the slider to scrub the animation, replay it, and try the background toggle. Template edits reload during this development session; Rust changes require rebuilding and restarting. Alternatively, cargo run runs the native app without a development server. Use cargo build to compile without launching. Distribution bundles are a separate packaging step, even when Cargo builds optimized artifacts.

Use --target=ios or --target=ipados for a simulator session; see mobile development.

Project anatomy

Open the project in your editor. These are the main roles to recognize:

File or directory	What it contains
`Cargo.toml`	The Rust package definition, dependencies, and optional Pax project metadata.
`src/main.rs`	Calls `pax_kit::init!()?.run()` to initialize and run the UI in the native application process.
`src/lib.rs`	The scene's state and event handlers, plus `pax_kit::runnable! { root: crate::Example }`. An optional `init` callback customizes root construction.
`src/lib.pax`	The starter's layout, logo instance, slider, and buttons.
Rust source (`.rs`)	Component definitions, application state, event handlers, and other application logic.
Pax templates (`.pax`)	UI elements, layout, styles, expressions, and bindings to event handlers. Templates can also be embedded in Rust source.
`assets/`, when present	Application media such as images and fonts.
`.pax/`	Generated build and development files, created by Pax's packaging tools. Make application changes in the source files above.

Pax templates describe the interface. Rust holds the state and behavior behind it. Expressions inside templates connect property values to what you see on screen. You'll work with these parts together as you build an interface.

The library builds as both rlib and cdylib. Its macros compile the Pax program during ordinary Rust compilation; your application needs no build.rs. The native executable has its own [[bin]] target, gated by required-features = ["standalone"], and starters enable standalone and designtime by default. On macOS, cargo run runs the native application. pax-cli run adds packaging, a development server, and template reload on the selected target. Xcode is required for Apple targets.

init! and init_with! initialize in the current native process; they do not parse application arguments or launch development tools. The designtime feature enables runtime inspection and template changes but does not start a server. Depending on a UI library never auto-launches it. See application setup for typed root construction and entry and mounting for platform details. Components can live in a nested ui/ module or a separate workspace library; see declare a runnable UI.

Make a first edit

Open src/lib.pax and find the Text element with id=replay_label. Change:

text="Replay"

to:

text="Play again"

Save to see the label update in your running pax-cli run session. The label is part of your scene; the animation behind AnimatedPaxLogo is a standard-library component. Follow @click=self.replay on its enclosing Group into src/lib.rs to see how the button resets and animates logo_progress. The slider binds to that same property, so it also follows playback.

Bare cargo run requires rebuilding after source edits. Rust changes require rebuilding and restarting on either path. See Hot reloading.

When something goes wrong

Symptom	What to check
`cargo` or `pax-cli` is not found	Confirm the installation finished successfully. Rust installs commands in `$HOME/.cargo/bin` on macOS/Linux or `%USERPROFILE%\.cargo\bin` on Windows. That directory must be on your shell's `PATH`; reopening the terminal after installation usually picks up the change.
A build cannot find the WebAssembly target or its standard library	Run `rustup target add wasm32-unknown-unknown`, then retry.
`wasm-pack` is not found	Run `cargo install wasm-pack --version 0.15.0`, then check `wasm-pack --version`.
A compiler, linker, or system library is missing	Revisit your workstation setup. On Windows, use the PowerShell session where you loaded the MSVC environment.
The project destination already exists	Choose a new directory name. Keep any existing project files.
The browser cannot connect	Check that `pax-cli run` is still running and use the local URL from that session.

For more build detail, run pax-cli run --target=web --verbose. If compilation fails, start with the first reported error. When asking for help, include that error, your workstation OS, and the output of pax-cli --version.

Where to go next

Continue with Template Language to learn how to describe an interface. Data Binding and Expressions explains how values flow into that interface, and Event Handling with Rust covers responding to input.

For hot reload, inspection, screenshots, and local reference, continue with Developer Workflow and Tools.

To choose another target or ship a release, see Targets, Build, and Deployment.

Further reference

The links below preserve earlier reference locations. Detailed workflow and packaging guidance lives in the linked chapters.

CLI telemetry

The first public CLI command prints the telemetry privacy notice and sends no telemetry. Later public commands enable minimal telemetry by default. See CLI Telemetry for the fields and opt-out controls.

Formatting Pax source

Use pax-cli fmt for Pax source and pax-cli fmt --check to check without writing. See Format Pax source for file selection, inline templates, and CI usage.

Hot reloading

Debug pax-cli run sessions reload .pax templates by default. Bare Cargo runs require rebuilding and restarting after source edits. For Rust changes, stop and rerun the app on every target; refresh the browser after rebuilding. See Hot reloading for the mode matrix, target boundaries, and project configuration.

Web public files

Use a project-root public/ directory for web-only files such as robots.txt and well-known metadata. See Web public files for copying, live serving, reserved paths, and the distinction from app assets.

Project Metadata

Configure titles, icons, Apple identity, and packaging values in [package.metadata.pax] in Cargo.toml. See Project metadata for the supported keys, target inheritance, and icon requirements. Apple apps can also declare typed Info.plist values and signing entitlements; see Apple property lists and entitlements.

Local release runs on iOS and iPadOS

Use pax-cli run --release --target ios or --target ipados for an optimized simulator run. Connected-device runs also accept a device selector and Apple development team. See Local release runs for signing, device selection, and the boundary with App Store distribution.

Pax Docs