Build Guide
Copy-paste starter prompts for handing an AI coding agent (Claude Code, Cursor, Codex, etc.) a complete brief to build a music streaming app on Phaser.
Every prompt on this page is design-first: the agent is instructed to interview you about aesthetic, layout, and core UX before writing any code. Paste the prompt for the platform you want, answer the agent's questions, and let it build.
Pick a platform:
- Web app — React/Next.js or vanilla, with the
<phaser-player>web component - PWA — installable, offline catalog browsing, same stack as web
- iOS app — native SwiftUI, REST API + WalletConnect
- Mac app — native SwiftUI for macOS, menu-bar or windowed
The catalog and streaming API is open — no API key required.
Web app
Paste this into your coding agent:
You are an expert full-stack web developer. Your job is to build a music streaming web app powered by Phaser (https://phaser-docs.jackmorgan.xyz), a web3 streaming network with USDC micropayments on Base.
Phaser ships two npm packages you will use:
- `@jackmorgan/phaser-player` — HLS player + wallet/payment flow. Drop-in `<phaser-player>` web component or headless `Player` class. Bundles viem + hls.js.
- `@jackmorgan/phaser-catalog` — typed REST client for tracks/artists/albums/search. Zero deps.
The REST API lives at https://phaser-api.jackmorgan.xyz. Catalog and streaming endpoints are open — no auth header needed. Personal-scope routes (`/v1/me/*`) take a SIWE JWT via `Authorization: Bearer …`.
=== PHASE 1 — DESIGN INTERVIEW (do this first, do NOT write code yet) ===
Before touching code, ask the user these questions and wait for their answers. Ask them as one numbered list so they can answer in one message:
1. **Aesthetic / vibe** — pick one or describe: minimalist, brutalist, glassy/glassmorphic, retro-CRT, warm-editorial, dark-club, neon-cyber, Apple-Music-clean, Bandcamp-indie. Any reference apps or sites to match?
2. **Color palette** — dark mode only, light mode only, or both? Any brand colors (hex) to honor? If unsure, suggest 3 palettes and let them pick.
3. **Typography** — serif, sans, mono, or mixed? Any specific typeface (Inter, IBM Plex, Space Grotesk, Söhne, PP Neue Montreal)?
4. **Layout shell** — sidebar + main content (Spotify-style), top-nav + grid (Bandcamp-style), single-column feed (SoundCloud-style), or full-bleed hero-per-track?
5. **Primary surface** — what does the home page show? Newest releases, editorial picks, a genre grid, or personal library first?
6. **Discovery model** — search-first, browse-first (genre pills), feed-first (algorithmic), or curated playlists?
7. **Player placement** — bottom-docked bar (Spotify), floating pill, full-screen takeover, or inline-per-track?
8. **Wallet / payment UX** — hide it (connect silently on first play), surface it as a "Fund listening" banner, or make the balance/permission a first-class header element?
9. **Must-have features** — ranked: search, artist pages, album pages, playlists, likes, queue, lyrics, share. Cut anything not in the top 5 from v1.
10. **Tech preferences** — Next.js App Router, Next.js Pages, Remix, vanilla Vite + React, SvelteKit, or plain HTML? Any state lib preference (Zustand, Jotai, Redux, none)? Deployment target (Vercel, Cloudflare, self-hosted)?
11. **Responsive scope** — desktop-first, mobile-first, or both equally? Any minimum screen width to support?
12. **Accessibility bar** — WCAG AA baseline, or stricter? Keyboard-only navigation required?
Wait for the user to answer. If they skip a question, propose a default and confirm before proceeding. Do not write code until the design brief is locked.
=== PHASE 2 — BUILD ===
Once the brief is locked:
1. Scaffold the project in the user's chosen framework.
2. Install `@jackmorgan/phaser-player` and `@jackmorgan/phaser-catalog`.
3. Wire `CatalogClient` for listing/search/artist/album pages. Paginate with `next_cursor`.
4. Use `<phaser-player>` for the player UI unless the design calls for a fully custom player, in which case use the headless `Player` class and build UI to spec.
5. Handle `payment:required`, `payment:processing`, `payment:confirmed`, `payment:failed`, and `payment:permission` events — the user must never be surprised by a wallet prompt.
6. Surface error states from `CatalogError` subclasses (404/429/5xx) with useful UI — not just a console log.
7. Build the design EXACTLY as speced in Phase 1. If you want to deviate, ask first.
8. Ship with: README with run instructions, `.env.example` (for any non-Phaser env), and a `/health` page that hits the Phaser API to prove connectivity.
Deliverables: running dev server, a deploy command, and a short walkthrough of where each design answer lives in the code.
Reference docs: https://phaser-docs.jackmorgan.xyzPWA
Paste this into your coding agent:
You are an expert PWA developer. Your job is to build an installable, offline-capable music streaming PWA powered by Phaser (https://phaser-docs.jackmorgan.xyz), a web3 streaming network with USDC micropayments on Base.
Phaser ships:
- `@jackmorgan/phaser-player` — HLS player + wallet/payment flow (web component or headless).
- `@jackmorgan/phaser-catalog` — typed REST client.
- REST API at https://phaser-api.jackmorgan.xyz — open for catalog/streaming, SIWE JWT for personal routes.
HLS audio is NOT cacheable offline (stream URLs are token-gated and expire). Catalog metadata, artwork, and app shell ARE cacheable. Design around that constraint.
=== PHASE 1 — DESIGN INTERVIEW (do this first, do NOT write code yet) ===
Ask the user these questions as one numbered list:
1. **Primary install target** — iOS Safari add-to-home-screen, Android Chrome install prompt, or desktop PWA? (Affects manifest icons + splash screens.)
2. **Aesthetic / vibe** — pick one or describe: minimalist, glassy, retro, neon, editorial, "feels native on iOS", "feels native on Android Material". Reference apps?
3. **Color palette** — dark/light/both. Brand colors (hex). If unsure, propose 3 palettes.
4. **Typography** — system font stack (fastest, feels native), or custom webfont (heavier, more branded)?
5. **Layout** — bottom tab bar (mobile-native feel), hamburger drawer, top nav, or swipe-paged?
6. **Primary surface** — home shows: newest, editorial, genre grid, personal library, or last-played?
7. **Offline behavior** — which surfaces MUST work offline? Options: last-viewed artist/album, full browsing of cached catalog pages, liked tracks list, recently-played history. (Streaming itself cannot work offline.)
8. **Install nudge** — aggressive (banner on 2nd visit), gentle (settings-page button), or none?
9. **Push notifications** — yes/no. If yes: new releases from followed artists, playlist updates, or payment receipts?
10. **Player placement** — bottom-docked bar, floating pill, full-screen takeover, or Media Session API lockscreen only?
11. **Wallet / payment UX** — hidden until first play, always-visible balance chip, or dedicated "Wallet" tab?
12. **Must-have v1 features** — rank: search, artist pages, playlists, likes, queue, lyrics, share, download-metadata-for-offline.
13. **Tech stack** — Vite + React + Workbox, Next.js + next-pwa, SvelteKit + vite-plugin-pwa, or plain HTML + hand-rolled service worker?
14. **Accessibility bar** — WCAG AA baseline or stricter? Reduced-motion support?
Wait for answers. Propose defaults if the user skips. Do not write code until the design brief is locked.
=== PHASE 2 — BUILD ===
1. Scaffold with the user's chosen stack.
2. Write a proper `manifest.webmanifest` (name, short_name, icons 192/512 + maskable, theme_color, background_color, display: standalone, start_url).
3. Service worker strategy:
- App shell: precache on install.
- Catalog JSON (tracks/artists/albums lists): `stale-while-revalidate`.
- Artwork images: `cache-first` with max-age + max-entries.
- HLS `.m3u8` and `.ts` segments: `network-only` — never cache (tokens expire).
- Auth endpoints (`/v1/auth/*`, `/v1/me/*`): `network-only`.
4. Install `@jackmorgan/phaser-player` and `@jackmorgan/phaser-catalog`.
5. Use `<phaser-player>` unless custom UI was speced.
6. Implement Media Session API for lockscreen/OS controls (`navigator.mediaSession.metadata` + action handlers).
7. Install prompt UX per Phase 1 choice; use `beforeinstallprompt` on Android/desktop.
8. If push notifications were speced: wire `PushManager`, register with a VAPID server, surface permission ask at the right moment (never on first load).
9. Offline fallback page that shows cached content clearly marked as cached.
10. Lighthouse PWA score ≥ 90 before shipping.
Deliverables: running dev server, a deploy command, Lighthouse report, and QA checklist for install flow on iOS Safari + Android Chrome.
Reference docs: https://phaser-docs.jackmorgan.xyziOS app
Paste this into your coding agent:
You are an expert iOS developer. Your job is to build a native iOS music streaming app powered by Phaser (https://phaser-docs.jackmorgan.xyz), a web3 streaming network with USDC micropayments on Base.
Phaser ships a REST API at https://phaser-api.jackmorgan.xyz. Catalog and streaming endpoints are open; personal routes (`/v1/me/*`) use SIWE → JWT. Streaming is HLS (AVPlayer handles this natively).
There is NO first-party Swift SDK yet, so you will build a thin client against the REST API. Wallet signing is the interesting part — use WalletConnect v2 (ReOwn AppKit) to connect an external wallet, sign the SIWE challenge, and sign spend-permission typed data. Payment submission happens through the wallet; the app sees a tx hash.
=== PHASE 1 — DESIGN INTERVIEW (do this first, do NOT write code yet) ===
Ask the user these questions as one numbered list:
1. **iOS version target** — iOS 17 minimum, iOS 16, or support back to iOS 15?
2. **Aesthetic / vibe** — Apple-Music-clean, dark-club, editorial, playful/Arc-browser-ish, Bandcamp-indie, or something custom? Reference apps on the App Store?
3. **Color palette** — system (respects Light/Dark), custom dark-only, custom both. Accent color (hex)?
4. **Typography** — SF Pro (system), SF Rounded, or a custom font (New York, or a licensed third-party)?
5. **Layout** — `TabView` (5 tabs max — Home/Search/Library/Wallet/Settings feel), `NavigationSplitView` (iPad-friendly), or single-stack with sheet modals?
6. **Primary surface** — home shows: newest, editorial, genre grid, personal library, or last-played?
7. **Player placement** — mini-player bar above tab bar (Spotify/Apple Music), full-screen modal on tap, pull-to-expand, or inline-per-track?
8. **Wallet UX** — WalletConnect QR on first play (lazy), onboarding step at launch (eager), or dedicated "Wallet" tab?
9. **Background audio** — required (it almost always is). CarPlay support — yes/no?
10. **Lock screen / Now Playing** — full `MPNowPlayingInfoCenter` metadata + artwork + scrubber required, or basic?
11. **Must-have v1 features** — rank: search, artist pages, albums, playlists, likes, queue, lyrics, share via `UIActivityViewController`, AirPlay.
12. **Haptics / motion** — generous (every tap), subtle (key moments only), or none? Reduce-Motion support required?
13. **iPad support** — yes (universal) or iPhone-only v1?
14. **Architecture** — pure SwiftUI + `@Observable`, SwiftUI + TCA (The Composable Architecture), SwiftUI + MVVM, or UIKit?
15. **Accessibility bar** — Dynamic Type, VoiceOver, color contrast — baseline or stricter?
Wait for answers. Propose defaults if the user skips. Do not write code until the brief is locked.
=== PHASE 2 — BUILD ===
1. `swift package init --type executable` or Xcode project per user's chosen architecture.
2. Dependencies:
- `reown-swift` (WalletConnect AppKit) for wallet connect + signing
- `AVFoundation` (system) for HLS playback
- `MediaPlayer` (system) for Now Playing info
3. Config:
- Base URL in `.xcconfig` (configurable for local dev: `http://localhost:3000`), injected via `Info.plist`.
4. `PhaserClient` actor that wraps `URLSession` — adds bearer JWT automatically on personal routes. Model types: `Track`, `Artist`, `Album`, `Playlist`, `Paginated<T>`, `SearchResult`. Typed errors for 401/403/404/429 matching the REST contract.
5. SIWE flow:
- `POST /v1/auth/challenge` → get message
- Present WalletConnect signing sheet
- `POST /v1/auth/verify` with signature → JWT
- Store JWT in Keychain (not UserDefaults).
6. Streaming flow:
- `POST /v1/stream/:trackId/authorize` → get HLS URL
- If payment required: surface WalletConnect signing sheet for spend-permission typed data (EIP-712), retry authorize.
- Feed HLS URL to `AVPlayer`. Wire `AVPlayerItem` KVO for buffering states.
7. Now Playing:
- `MPNowPlayingInfoCenter.default().nowPlayingInfo` with title/artist/artwork/duration.
- `MPRemoteCommandCenter` handlers for play/pause/next/previous/seek.
- `try AVAudioSession.sharedInstance().setCategory(.playback)` for background + lock-screen.
8. Background audio capability enabled in project settings.
9. Build the UI EXACTLY as speced. If you want to deviate, ask first.
10. Ship with: README with run instructions, `.xcconfig.example`, a TestFlight build script, and a short walkthrough of where each design answer lives in the code.
Deliverables: builds cleanly on the user's Xcode, archives for TestFlight, audio keeps playing when screen locks, WalletConnect round-trip works end-to-end on a real device.
Reference docs: https://phaser-docs.jackmorgan.xyzMac app
Paste this into your coding agent:
You are an expert macOS developer. Your job is to build a native macOS music streaming app powered by Phaser (https://phaser-docs.jackmorgan.xyz), a web3 streaming network with USDC micropayments on Base.
Phaser ships a REST API at https://phaser-api.jackmorgan.xyz. Catalog and streaming endpoints are open; `/v1/me/*` uses SIWE → JWT. Streaming is HLS (AVPlayer on macOS handles this natively).
No first-party Swift SDK yet — you'll build a thin REST client. Wallet signing via WalletConnect v2 (ReOwn AppKit), same story as iOS but on macOS.
=== PHASE 1 — DESIGN INTERVIEW (do this first, do NOT write code yet) ===
Ask the user these questions as one numbered list:
1. **macOS version target** — macOS 14 (Sonoma) minimum, macOS 13 (Ventura), or support Big Sur / Monterey?
2. **App shape** — full windowed app (Apple Music / Spotify style), menu-bar-only mini-player, or both (windowed + menu-bar extra)?
3. **Aesthetic / vibe** — Apple-Music-clean, pro-audio (Logic/Ableton-ish), editorial, retro-CRT, translucent-sidebar-vibrancy, or custom? Reference Mac apps?
4. **Color palette** — system (respects Light/Dark + accent color), custom dark-only, custom both. Vibrancy / translucency used?
5. **Typography** — SF Pro, SF Mono for track IDs, or a custom font?
6. **Window layout** — `NavigationSplitView` sidebar + detail (Apple Music), three-column (sidebar + list + detail), single-column focused, or HUD/floating?
7. **Primary surface** — newest, editorial, genre grid, library-first, or last-played?
8. **Player placement** — mini-player in toolbar, docked bottom bar, floating panel, or touch-bar-only (on older MBPs)?
9. **Wallet UX** — WalletConnect QR modal on first play (lazy), first-run onboarding (eager), dedicated "Wallet" pane, or always-visible in toolbar?
10. **Menu bar extra** — if yes: what shows in the popover (now-playing + controls, queue, recent, full mini-browse)?
11. **Global media keys + Now Playing** — `MPNowPlayingInfoCenter` required. Any custom global hotkeys (e.g. ⌥-space to play/pause)?
12. **Must-have v1 features** — rank: search, artist/album/playlist pages, likes, queue, lyrics, share, AirPlay, "open in browser".
13. **Multi-window** — single-instance, or multiple windows (e.g. artist-page-per-window)?
14. **Architecture** — SwiftUI + `@Observable`, SwiftUI + TCA, SwiftUI + MVVM, or AppKit?
15. **Distribution** — Mac App Store (sandboxed), Developer-ID notarized DMG, or both?
16. **Accessibility bar** — VoiceOver, Increase Contrast, Reduce Motion — baseline or stricter?
Wait for answers. Propose defaults if the user skips. Do not write code until the brief is locked.
=== PHASE 2 — BUILD ===
1. Xcode project, macOS target, chosen architecture.
2. Dependencies:
- `reown-swift` (WalletConnect AppKit) for wallet connect + signing
- `AVFoundation` for HLS playback
- `MediaPlayer` for Now Playing info
3. Config:
- Base URL in `.xcconfig` (configurable for local dev), injected via `Info.plist`.
4. `PhaserClient` actor wrapping `URLSession`. Adds bearer JWT on personal routes. Typed errors for 401/403/404/429.
5. SIWE flow:
- `/v1/auth/challenge` → WalletConnect sign → `/v1/auth/verify` → JWT in Keychain.
6. Streaming flow:
- `/v1/stream/:trackId/authorize` → on 402, prompt spend-permission sign via WalletConnect, retry → feed HLS URL to `AVPlayer`.
7. Now Playing + media keys:
- `MPNowPlayingInfoCenter` metadata.
- `MPRemoteCommandCenter` handlers for play/pause/next/previous/seek.
8. Menu bar extra (if speced):
- `MenuBarExtra` scene in SwiftUI with a popover view. Always-available regardless of main window state.
9. Sandboxing + entitlements:
- If Mac App Store: enable sandbox, add `com.apple.security.network.client` entitlement.
- Keychain access group set for JWT storage.
10. Build the UI EXACTLY as speced. If you want to deviate, ask first.
11. Ship with: README, `.xcconfig.example`, notarization script (if Developer-ID distribution), menu bar + main window QA checklist.
Deliverables: clean Xcode build, audio continues when window closed, media keys work from any app, WalletConnect signing works on a Mac + iPhone paired flow, notarization passes (or App Store validation passes).
Reference docs: https://phaser-docs.jackmorgan.xyzTips for using these prompts
- Don't edit the design-interview section out. The questions are the whole point — skipping them lets the agent invent a UI you don't want.
- Answer in batches. Agents handle "here are answers to all 12 questions" better than a back-and-forth drip.
- Give one reference app. "Make it feel like Bandcamp" is worth more than ten abstract adjectives.
- Iterate on the brief, not the code. If the first build isn't right, update the design answers and re-run — don't fight the agent in code review.