Wavlake Music Client Example

A minimal music streaming client built with Next.js and the @wavlake/ecash SDK. Demonstrates ecash wallet integration, music browsing via the Wavlake catalog API, and audio playback.

Features

• 🔑 Nostr Auth — Generate or import a Nostr keypair
• 💰 Ecash Wallet — Deposit credits via Lightning, view balance, manage Cashu proofs
• 🔍 Music Search — Browse Wavlake's catalog of tracks
• 🎵 Audio Playback — Stream tracks directly in the browser
• 🎨 Dark UI — Clean, minimal dark-themed interface

Tech Stack

• Next.js 16 (App Router)
• @wavlake/ecash — Cashu ecash wallet SDK
• Tailwind CSS v4
• Wavlake Catalog API — Music content

Getting Started

Prerequisites

• Node.js 18+
• npm

Install

git clone https://github.com/wavlake/music-client-example.git
cd music-client-example
npm install --legacy-peer-deps

Note: --legacy-peer-deps is needed because the ecash SDK currently requires React 18, but Next.js 16 ships React 19.

Run

npm run dev -- --webpack

Note: The --webpack flag is needed because the ecash SDK ships raw TypeScript files that require webpack's extensionAlias config. Turbopack (Next.js 16 default) doesn't support this yet.

Open http://localhost:3000.

Build

npx next build --webpack

How It Works

1. Auth: Generate a Nostr keypair (stored in localStorage)
2. Wallet: The app wraps everything in <EcashProvider> from the ecash SDK, configured with a Cashu mint URL
3. Deposit: Use useMint() to create a Lightning invoice, pay it, and mint ecash proofs
4. Browse: Search Wavlake's catalog API for tracks
5. Play: Click a track to stream it via the liveUrl from the API

SDK Integration Notes

The ecash SDK provides:

• EcashProvider — React context with mint URL and storage config
• useWallet() — Balance, proofs, add/remove/swap proofs
• useMint() — NUT-04 deposit flow (create quote → pay invoice → mint proofs)
• createLocalStorageAdapter() — Browser storage for proof persistence

See DX-FRICTION-LOG.md for a detailed developer experience report.

Known Limitations

• Payment for streams is not yet implemented (the SDK focuses on wallet operations, not content payments)
• The Wavlake catalog API is undocumented — endpoints were discovered by experimentation
• The ecash SDK ships raw TypeScript and requires special bundler configuration

License

MIT