---
title: "Demo app"
description: "An overview of the Wavelength reference integration app - what it demonstrates and how to run it locally."
canonical: https://wavelength.lightning.engineering/web/support/demo-app/
---

> Docs index: https://wavelength.lightning.engineering/llms.txt

# Demo app

> **Try it live**
>
> A hosted signet demo runs in your browser at <https://wavelength.lightning.engineering/demo/>. No clone or local setup required.

## The reference integration

The **`web-wallet-demo`** app in the Wavelength monorepo is a full React integration you can read, run, and copy patterns from. It is not a separate product; it exercises the same `@lightninglabs/wavelength-web` and `@lightninglabs/wavelength-react` packages your app would use.

What it demonstrates:

- **`WavelengthProvider`** with an injected `createWebWalletEngine()` engine (self-hosted runtime assets, worker mode, optional RPC debug logging).
- **Multiple named wallets per origin**, tracked in a `localStorage` registry (`src/lib/walletRegistry.ts`): a name, network, and unlock method per wallet, with sequential switching between them by stopping the running engine and starting the next entry.
- **Phase-based routing** from `useWallet()`: create/unlock, backup, syncing, ready, stopped, and error screens driven by `phase` and `useWalletInfo()`, with a wallet list and a create/restore flow shown before any engine starts.
- **Password and passkey onboarding** via `useWalletCreate` / `useWalletUnlock` and `useWalletPasskey(...)`, with the credential id persisted on the wallet’s registry entry for scoped unlock (`src/lib/walletRegistry.ts`). The demo passes a ceremony built with `createWebPasskeyCeremony` so passkey timing lands on the same sink as its other performance samples; `webPasskeyCeremony` is the equivalent without instrumentation.
- **Core wallet flows**: deposit address, Lightning receive, send (prepare and confirm), balance and activity, and settings.
- **Network presets** for signet, testnet, and regtest, each wallet permanently bound to the network chosen at creation (`endpointsForNetwork()` in `runtime-config.ts` mirrors public gateway URLs and local arktest ports).
- **Production-like hosting concerns**: COOP/COEP headers in `vite.config.ts`, self-hosted WASM binaries under `public/runtime/<version>/`, persistent storage request, and a local wipe path that clears OPFS and app markers (`src/lib/wipeLocalData.ts`).

Treat the demo as the source of truth for wiring details that docs summarize. Key entry points: `src/main.tsx` (engine bootstrap), `src/App.tsx` (orchestration), `src/lib/walletRegistry.ts` (the wallet list), and `src/lib/runtime-config.ts` (gateway defaults).

See also: [`createWebWalletEngine`](/reference/wavelength-web/#createWebWalletEngine), [`useWallet`](/reference/wavelength-react/#useWallet), and [`useWalletPasskey`](/reference/wavelength-react/#useWalletPasskey) in the API reference for details behind each of these bullets.

## How to run it

Clone the monorepo, install dependencies, and start the demo dev server. Step-by-step commands (including `wasm:local` for a fresh WASM build and regtest/testnet overrides) live on the dedicated run page:

**[Run the demo app](/web/get-started/run-the-demo-app/)**

Out of the box the demo’s create-wallet screen offers **signet** and **testnet** against Lightning Labs public gateways; no local backend is required for either. Regtest is a dev-only option, hidden unless you open the demo with `?regtest=1`. For regtest, start [arktest](https://github.com/lightninglabs/wavelength) locally, pick regtest on the create screen, and enter the ports it prints in the collapsed “Advanced endpoints” section.

Runtime assets are staged (never committed) under `public/runtime/<RUNTIME_MANIFEST_VERSION>/`. Before the first `dev:local` run, and after upgrading the SDK or rebuilding WASM from `wavelength`, run `pnpm --filter web-wallet-demo run wasm:local` to stage fresh binaries; locally built assets cannot match the pinned release digests, so `dev:local` (not plain `dev`) is what disables verification for them. See [Run the demo app](/web/get-started/run-the-demo-app/) for the full command.

React Native readers: see [Run the demo app](/react-native/get-started/run-the-demo-app/) for the mobile counterpart, which mirrors this demo screen for screen.