Demo app

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).
  • Phase-based routing from useWallet(): connect, create/unlock, backup, syncing, ready, stopped, and error screens driven by phase and useWalletInfo().
  • Password and passkey onboarding via useWalletCreate / useWalletUnlock and useWalletPasskey(webPasskeyCeremony), including credential id persistence in localStorage for scoped unlock (see src/lib/walletKind.ts).
  • Core wallet flows: deposit address, Lightning receive, send (prepare and confirm), balance and activity, settings, and runtime configuration forms.
  • Network presets for signet, testnet, and regtest (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), and src/lib/runtime-config.ts (gateway defaults).

See also: createWebWalletEngine, useWallet, and 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

Out of the box the demo boots a signet wallet against Lightning Labs public gateways. No local backend is required for signet. For regtest, start arktest locally and point the runtime form at the ports it prints.

Runtime assets are staged (never committed) under public/runtime/<RUNTIME_MANIFEST_VERSION>/. Before the first pnpm dev, and after upgrading the SDK or rebuilding WASM from wavelength, run pnpm --filter web-wallet-demo run wasm:local to stage fresh binaries.

React Native readers: see Run the demo app for the mobile counterpart, which mirrors this demo screen for screen.