---
title: "Installation"
description: "How to add the wavelength-web and wavelength-react packages to your project, including required peer dependencies."
canonical: https://wavelength.lightning.engineering/web/get-started/installation/
---

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

# Installation

## The packages

The Wavelength SDK ships as three npm packages. You install one or two of them depending on your stack:

| Package                           | What it is                                                                                                                        |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `@lightninglabs/wavelength-core`  | Types, the `WavelengthClient` interface, errors, and enums. Pulled in transitively; you rarely install it directly.               |
| `@lightninglabs/wavelength-web`   | The browser WASM transport. Framework-agnostic: use it from vanilla JS, Vue, Svelte, or React. Re-exports everything from `core`. |
| `@lightninglabs/wavelength-react` | React provider and hooks. Transport-agnostic: it takes an injected engine and depends only on `core`.                             |

**React apps** need the web transport and the React bindings:

```bash
npm install @lightninglabs/wavelength-web @lightninglabs/wavelength-react
```

**Vanilla JS, Vue, Svelte, or other non-React frameworks** need only the web transport:

```bash
npm install @lightninglabs/wavelength-web
```

Before wiring up the code samples below, make sure the browser environment you’re deploying to meets the [requirements](/web/get-started/requirements/) and serves your app with the headers described in [Cross-origin isolation](/web/get-started/cross-origin-isolation/). The Wavelength SDK’s WebAssembly runtime will not start without them.

## Peer deps

`@lightninglabs/wavelength-react` declares `react` as a peer dependency, with an accepted range of `^18.0.0 || ^19.0.0`. Your app must also provide `react-dom` (or the equivalent for your React renderer). Either major version, 18 or 19, works:

```bash
npm install react react-dom
```

Build the wallet engine once near the root of your app. `createWebWalletEngine` accepts `WebWalletEngineOptions` (for example `runtimeBaseUrl` pointing at hosted WASM assets, see [Hosting runtime assets](/web/get-started/hosting-runtime-assets/)), plus `config` and `autoStart` to boot the embedded daemon as soon as the runtime is ready, no boot effect needed.

```tsx
import { WavelengthProvider, useWallet, useWalletBalance } from '@lightninglabs/wavelength-react';
import { createWebWalletEngine, defaultConfig } from '@lightninglabs/wavelength-web';

// Configure transport options once. runtimeBaseUrl points at the hosted WASM
// asset folder.
const engine = createWebWalletEngine({
  runtimeBaseUrl: 'https://your-host/wavewalletdk/',
  config: defaultConfig('signet'),
  autoStart: true,
});

export function App() {
  return (
    <WavelengthProvider engine={engine}>
      <Wallet />
    </WavelengthProvider>
  );
}

function Wallet() {
  const { phase, error } = useWallet();
  const balance = useWalletBalance();

  if (phase !== 'ready') {
    return <p>Loading… ({phase})</p>;
  }

  return <p>Spendable: {balance?.confirmedSat ?? 0} sats</p>;
}
```

`error` from `useWallet` holds the last fatal runtime-level error: set when the initial runtime load fails or when `start`/`stop` fails. Render it instead of dropping the failure on the floor.

For a non-React app, skip the provider and call `start` on the client directly after `ready()` resolves:

```ts
import { createWebClient, defaultConfig } from '@lightninglabs/wavelength-web';

const client = createWebClient({
  runtimeBaseUrl: 'https://your-host/wavewalletdk/',
});

await client.ready();
await client.start(defaultConfig('signet'));
```

## Next steps

- [Requirements](/web/get-started/requirements/): confirm the browser support matrix and backend services the Wavelength SDK needs.
- [Hosting runtime assets](/web/get-started/hosting-runtime-assets/): obtain the WebAssembly runtime asset set and serve it from your own host.
- [Quickstart](/web/get-started/quickstart/): wire up the provider, create a wallet, and send your first payment.