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 apps/web-wallet-demo/public/ folder is gitignored and ephemeral, so before running the demo you need to populate it with the runtime WASM binaries:

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:

Terminal
pnpm --filter web-wallet-demo dev

Open the URL Vite prints (typically http://localhost:5173). The demo boots a signet wallet out of the box: choose signet on the connect screen and the app boots with its own signet preset (signetDefaults 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 preview to serve the production build with the same headers.

Optional (wasm:local, regtest, testnet)

Rebuild runtime assets locally. When you are developing against a custom wavelength build, stage fresh WASM files into the demo’s public/ folder:

Terminal
# Expects a sibling wavelength checkout (override with WAVELENGTH_DIR)
pnpm --filter web-wallet-demo run wasm:local

This runs make wasm-wallet in wavelength and copies the full RUNTIME_ASSET_FILES set into public/runtime/<RUNTIME_MANIFEST_VERSION>/, the versioned path the demo’s runtimeBaseUrl points at.

Regtest with arktest. To exercise deposits, swaps, and exits against a local chain, run arktest in a separate terminal:

Terminal
# From a wavelength checkout
make build
./arktest-debug start --swapserver

Keep arktest running. In another terminal, print the connection URLs:

Terminal
./arktest-debug env

In the demo connect screen, switch the network to regtest. The defaults match arktest’s usual ports (7071 for Ark, 8501 for Esplora, 10032 for the swap server). Adjust the gateway fields if your arktest instance binds different ports.

At a high level the full local workflow is:

  1. Terminal 1: ./arktest-debug start --swapserver
  2. Terminal 2: pnpm --filter web-wallet-demo dev (optionally after wasm:local if you changed the daemon)
  3. Browser: select regtest, start the runtime, create or unlock a wallet

Testnet. Select testnet on the connect screen to boot with its own testnet preset (testnetDefaults in src/lib/runtime-config.ts), which mirrors the same public gateway URLs defaultConfig('testnet') would produce. No arktest instance 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.