| name | wavelength-react-native |
| description | Embed a self-custodial Lightning wallet in a React Native or Expo app with the Wavelength SDK (@lightninglabs/wavelength-react-native, @lightninglabs/wavelength-react). Use when integrating Wavelength into a React Native or Expo app, creating a native wallet engine, sending or receiving Lightning payments on device, wiring WavelengthProvider with a native engine, or adding native passkey protection. Triggers include "wavelength react native", "createNativeWalletEngine", "embed a Lightning wallet in React Native", "createNativePasskeyCeremony", and "Expo wallet". |
Wavelength React Native integration
Wavelength embeds a self-custodial Lightning wallet in a React Native or Expo
app. The wallet daemon is compiled directly into the app binary; there is no
node to run, no backend to operate, and nothing listening on a socket.
Docs index: https://wavelength.lightning.engineering/llms.txt. Every docs page
has a markdown twin at the same URL with .md appended; fetch those.
Packages
Check the npm registry for current versions; do not rely on memorized ones.
@lightninglabs/wavelength-react-native: the native transport. A Turbo
Module wrapping the wallet runtime compiled into the app binary.
createNativeClient() builds a raw client; createNativeWalletEngine()
wraps it in a WalletEngine and is the factory to use with the React
provider. Re-exports everything from core.@lightninglabs/wavelength-react: <WavelengthProvider> plus hooks. Takes an
injected engine; it does not depend on the react-native package.
Task routing
Critical rules
- Create the engine with
createNativeWalletEngine() from
wavelength-react-native and pass it to <WavelengthProvider engine={...}>.
Build the engine once, outside the component tree (module scope), and
inject the same instance on every render.
- Requires React Native 0.76 or newer, iOS 15.1+, and Android minSdk 24.
The New Architecture must be enabled. This package is New Architecture
only; it does not support the legacy architecture.
- 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.
- The native wallet runtime binaries (
Wavewalletdk.aar,
Wavewalletdk.xcframework) are not bundled in the npm package. Stage them
before the first build from the paired wavelength release: the .aar is
copied into android/libs/, while the iOS archive is unpacked to one side,
has its headers rewritten (clang rejects gomobile's @import before it will
compile the package's Objective-C++ glue), and only then replaces any
ios/Wavewalletdk.xcframework already there. Follow the installation page
above rather than improvising it. From a checkout of the SDK repository, the
bindings:fetch script does all of it for you.
- Passkey ceremonies are injected. Pass
createNativePasskeyCeremony({ rpId })
from wavelength-react-native into useWalletPasskey(ceremony); do not
implement platform authentication calls by hand. The rpId domain needs
an assetlinks.json (Android) and an apple-app-site-association plus
Associated Domains entitlement (iOS); see the passkey setup page above.
iOS passkey support is experimental.
- Activity arrives as typed
activity events, re-emitted from native
wavelengthActivity device events; do not poll for state changes by hand.
Verify the integration
After wiring, confirm: the app builds and launches on a device or
simulator via a development build (not Expo Go), the engine's phase
(from useWallet()) reaches ready, and an invoice can be created.
