oriel dev runs the app against the frontend’s dev server (Vite by default): edits to the page reload in place with the dev server’s hot module replacement, and edits to the Zig code rebuild and restart the app on their own. Development builds are Debug builds with the web inspector on, load the page from the dev server instead of embedded files, and stop everything they started when you stop them.

Use oriel dev while working on the app, oriel run to try the production build, and oriel check for a fast type-check of the Zig code. Phones have their own dev commands (oriel android dev, oriel ios dev).

Availability

An app needs a frontend dev server (Frontend.dev, on by default) for oriel dev; without one (the vanilla template) there is no dev step: use oriel run and rerun after edits.

Quick start

oriel init my-app        # React + Vite template
cd my-app
oriel dev                # Vite on http://localhost:5173/, the app against it

Edit frontend/src/App.tsx: the window updates in place. Edit src/main.zig: the terminal shows

[oriel dev] Change detected (main.zig). Recompiling...
[oriel dev] Rebuilt successfully. Restarting app...

Close the window, press Ctrl-C, or kill the zig process: the app, the dev server and the runner all stop.

How it works

flowchart LR
  CLI["oriel dev"] -->|"zig build dev"| Build["npm install (once),<br/>types, build-dev"]
  Build --> Runner["dev_runner"]
  Runner -->|"starts, own process group"| Vite["Dev server<br/>(vite --port 5173)"]
  Runner -->|"starts with ORIEL_DEV_EXTERNAL=1"| App["NAME-dev<br/>(Debug, loads the dev server)"]
  Vite -->|"HMR over the page's connection"| App
  Edit["edit src/*.zig"] -->|"watch"| Runner
  Runner -->|"zig build build-dev,<br/>same -D options"| Rebuild["rebuild"]
  Rebuild -->|"success: restart"| App

oriel dev finds the project root (the nearest directory with a build.zig.zon), resolves the project’s Zig (CLI), and runs zig build dev. That step, from oriel.addApp in build.zig:

1. runs npm install when frontend/node_modules is missing;
2. regenerates frontend/src/oriel.ts from Commands and Events;
3. builds the development executable <name>-dev (Debug unless -Doptimize says otherwise) whose oriel_app.build.dev points at the dev server and whose embedded assets are empty;
4. runs dev_runner (tools/dev_runner.zig).

dev_runner starts the dev server command in the frontend directory and the app in the project root, each in its own process group, and sets ORIEL_DEV_EXTERNAL=1 so the app doesn’t start a second dev server. The app’s window loads the dev server’s URL, retrying every 250 ms while the server starts (every 250 ms on Linux, up to App.Dev.timeout_ms, 30 s); the page then gets hot module replacement straight from the dev server.

It watches the .zig files under src/ (skipping directories that start with ., node_modules, dist, zig-out and zig-pkg). After a change it waits 100 ms for more writes, stops the app, runs zig build build-dev with the same -D options zig build dev got, and on success starts the new build. After a failed build no app runs until the next change builds. When the app exits with code 0 (the window closed) dev mode ends; another exit code waits for a change and restarts.

Stopping is thorough: on Linux dev_runner and the app get PR_SET_PDEATHSIG, dev_runner watches the zig process through a pidfd, and on exit kills each child’s whole process group (SIGTERM, then SIGKILL after 0.5 s). macOS polls the zig process and the app watches ORIEL_DEV_RUNNER_PID. On Windows dev_runner runs in a kill-on-close job object, so closing the console takes everything with it.

Examples

Pass arguments and build options

oriel dev -Dnative_ui                  # the native renderer, rebuilds keep the option
oriel dev -Ddev_debug_info=false       # faster rebuilds, no symbolized stack traces
oriel dev -- --profile work            # arguments for the app (after --)

A different dev server

// build.zig
.frontend = .{
    .dir = "frontend",
    .dev = .{
        .url = "http://localhost:3000/",
        .command = &.{ "npm", "run", "dev", "--", "--port", "3000" },
    },
},

The URL’s origin is trusted like the app’s own in dev builds, so it must be the server’s exact scheme://host:port. An empty command starts no server: run it yourself.

Inspect the page

Development builds are Debug builds, so App.Config.devtools is on:

To inspect a release build, set .devtools = true in App.Config (and remove it before shipping).

Type-check while editing

oriel check

zig build check compiles the app’s Zig code with a dev configuration and requests no binary, so Zig skips code generation and linking. No frontend build or embedded assets are needed.

Global hotkeys from a local build (Linux)

On Wayland the GlobalShortcuts portal only registers apps it can find, and a build in zig-out has no desktop entry:

oriel desktop-entry            # for oriel dev (the .Dev id)
oriel desktop-entry --release  # for oriel run

Run the app headless (Oriel’s own tests)

In the Oriel repository, scripts/headless.sh runs a GUI program on a private X display (Xvfb) and D-Bus session, so tests never touch the desktop:

scripts/headless.sh ./zig-out/bin/oriel-smoke --auto-quit
SHOT=out.png SHOT_AFTER=4 scripts/headless.sh ./zig-out/bin/my-app   # screenshot after 4 s

examples/smoke runs the security and module checks inside the real web view this way.

Reference

Development and production builds

Data directories (logs, the store) use the app id without .Dev, so the two builds share them.

Frontend.dev (build.zig)

Frontend.Dev, the dev server; .dev = null means the app has no dev mode (and no dev step). The other Frontend fields are on Building.

App.Dev (oriel_app.build.dev)

Generated from Frontend.dev into development builds:

Build steps

Environment

Logs and the console

The app’s std.log goes to stderr, so it shows in the oriel dev terminal, and to a log file once src/main.zig sets pub const std_options: std.Options = .{ .logFn = oriel.log.logFn };. Where the file is, levels, and the page’s console: Logging.

App.Config.devtools

Troubleshooting

Related

• CLI: every oriel command.
• Building: addApp, Frontend and the build options.
• Commands and events: the generated types.
• Logging: log files and the page’s console.
• Android and iOS: developing on phones.
• Security: what changes between dev and production pages.