---
title: "Installation"
description: "Install the React Native packages, enable the New Architecture, and stage the native wallet runtime."
canonical: https://wavelength.lightning.engineering/react-native/get-started/installation/
---

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

# Installation

## The packages

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

### @lightninglabs/wavelength-react-native

The native transport: a Turbo Module wrapping the wallet runtime compiled into your app binary. Re-exports the entire `core` surface, so it is the only wallet import an app needs besides the hooks package.

### @lightninglabs/wavelength-react

React provider and hooks. Transport-agnostic: it takes an injected engine (built with `createNativeWalletEngine`) and depends only on `core`.

## New Architecture and Expo

This package is New Architecture only; it does not support the legacy architecture. Enable the New Architecture in your app before installing.

Expo apps need a **development build**, not Expo Go: the native wallet runtime is a compiled module that Expo Go cannot load. `npx expo run:android` and `npx expo run:ios` both produce development builds that include it.

## iOS pods

`pod install` runs as part of `expo run:ios` or a standard React Native build; you do not need to run it separately in the common case. If `pod install` fails with a locale-related error, set `LANG=en_US.UTF-8` before retrying.

## Native runtime binaries

> **Native binaries are not bundled**
>
> The native wallet runtime binaries (`Wavewalletdk.aar`, `Wavewalletdk.xcframework`) are not included in the npm package. Stage them into the installed package before running `pod install` or a Gradle build, using the steps below.

Download `Wavewalletdk.aar` and `Wavewalletdk.xcframework.tar.gz` from the [wavelength release](https://github.com/lightninglabs/wavelength/releases) tagged with the `RUNTIME_MANIFEST_VERSION` that `@lightninglabs/wavelength-core` exports, then stage them from the installed package directory:

The release ships the raw gomobile output, whose headers use the Objective-C modules syntax. clang rejects that while compiling this package’s Objective-C++ glue, so the framework is unpacked into a scratch directory, rewritten there, and swapped in only at the end. A failed extraction then leaves whatever you already had staged intact:

```bash
cd node_modules/@lightninglabs/wavelength-react-native

TMP="$(mktemp -d ./.stage-XXXXXX)"
tar -xzf ~/Downloads/Wavewalletdk.xcframework.tar.gz \
  -C "$TMP" Wavewalletdk.xcframework
extracted=$?

find "$TMP/Wavewalletdk.xcframework" -name '*.h' \
  -exec sed -i.orig 's|@import Foundation;|#import <Foundation/Foundation.h>|' {} +
find "$TMP/Wavewalletdk.xcframework" -name '*.h.orig' -delete
if [ "$extracted" -eq 0 ] && [ -f ~/Downloads/Wavewalletdk.aar ] &&
   [ -f WavelengthReactNative.podspec ]; then
  mkdir -p android/libs
  cp ~/Downloads/Wavewalletdk.aar android/libs/
  rm -rf ios/Wavewalletdk.xcframework
  mv "$TMP/Wavewalletdk.xcframework" ios/
else
  echo "staging failed; previous binaries left in place" >&2
fi
rm -rf "$TMP"
```

Working from a checkout of the SDK repository instead, its `bindings:fetch` script does all of this for you, and `bindings:local` builds the binaries from a `wavelength` source checkout (for an unreleased daemon revision).

## Next steps

- [Quickstart](/react-native/get-started/quickstart/): wire up the provider, create a wallet, and send your first payment.
- [Requirements](/react-native/get-started/requirements/): confirm the platform, OS, and passkey requirements.