Run the demo app

Clone & install

The reference integration lives in the Wavelength monorepo at apps/web-wallet-demo. Clone the repository, install dependencies with pnpm, and build the workspace packages:

Terminal
git clone https://github.com/lightninglabs/wavelength-sdk.git
cd wavelength-sdk
pnpm install
pnpm build

The demo depends on the workspace packages @lightninglabs/wavelength-web and @lightninglabs/wavelength-react. The runtime WASM binaries under apps/web-wallet-demo/public/runtime/ are gitignored and ephemeral, so stage them before running the demo:

Terminal
pnpm --filter web-wallet-demo run wasm:local

See Hosting runtime assets for details on what this stages and how to point the demo at a different asset source.

Run

Start the Vite dev server from the monorepo root. Locally built runtime assets cannot match the pinned release digests, so dev:local disables integrity verification for this flow (VITE_RUNTIME_INTEGRITY=off):

Terminal
pnpm --filter web-wallet-demo run dev:local

Open the URL Vite prints (typically http://localhost:5173). The demo boots a signet wallet out of the box: the create-wallet screen preselects signet, using the preset endpointsForNetwork('signet') returns in src/lib/runtime-config.ts, which mirrors the same public gateway URLs defaultConfig('signet') would produce. No local backend is required.

Cross-origin isolation headers are configured in the demo’s Vite config so OPFS persistence works in every supported browser. See Cross-origin isolation for why these headers are required and how to configure them outside of Vite:

vite.config.ts
const crossOriginIsolation = {
  'Cross-Origin-Opener-Policy': 'same-origin',
  'Cross-Origin-Embedder-Policy': 'require-corp',
  'Cross-Origin-Resource-Policy': 'same-origin',
};


export default defineConfig({
  server: { headers: crossOriginIsolation },
  preview: { headers: crossOriginIsolation },
});

Use pnpm --filter web-wallet-demo run build:local && pnpm --filter web-wallet-demo preview to serve the production build with the same headers: locally built runtime assets cannot match the pinned release digests, so the plain build script would fail the integrity check the same way plain dev does.

Optional (testnet)

Rebuilding runtime assets. Re-run wasm:local whenever you change the daemon: it runs make wasm-wallet in wavelength (expecting a sibling checkout, overridable with WAVELENGTH_DIR) and copies the full RUNTIME_ASSET_FILES set into public/runtime/<RUNTIME_MANIFEST_VERSION>/, the versioned path the demo’s runtimeBaseUrl points at.

Testnet. Select testnet on the create-wallet screen to boot with the preset endpointsForNetwork('testnet') returns, which mirrors the same public gateway URLs defaultConfig('testnet') would produce. No local backend is needed.

Troubleshooting OPFS. If wallet persistence fails in the browser, confirm COOP/COEP headers are present:

Terminal
curl -sI http://localhost:5173 | grep -i cross-origin

Both Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy must appear in the response. See Troubleshooting / FAQ for more fixes, and the web guides for end-to-end wallet flows built on top of this demo.