CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project overview

stream-ui is a Vue 3 SSR frontend deployed on Cloudflare Workers. It uses Hono as the Worker server layer and a custom Vite SSR setup rather than Nuxt.

Common commands

Run all commands from stream-ui/.

# Install dependencies
bun install

# Start local dev server
bun run dev

# Build client + worker bundles
bun run build

# Preview production build locally
bun run preview

# Deploy to Cloudflare Workers
bun run deploy

# Regenerate Cloudflare binding types from Wrangler config
bun run cf-typegen

# Tail Cloudflare Worker logs
bun run tail

Notes:

This project uses Bun (bun.lock is present).
There is currently no configured test script.
There is currently no configured lint script.

Architecture

SSR entrypoints

src/index.tsx: Hono Worker entry; registers middleware, proxy routes, merge/display/manifest routes, then SSR routes
src/main.ts: shared app factory for SSR and client hydration
src/client.ts: client-side hydration entry
ssrPlugin.ts: custom Vite SSR plugin that builds the client first, injects the Vite manifest, and swaps environment-specific modules

Routing and app structure

Routes live in src/routes/index.ts.
Routing is SSR-aware: createMemoryHistory() on the server and createWebHistory() in the browser.
The app is split into:
- public pages
- auth pages
- protected dashboard/settings pages
Current protected areas include videos, notification, and settings/* routes.

State and hydration

Pinia is used for app state.
@pinia/colada is used for server-state/query hydration.
SSR serializes Pinia state into $p and query cache into $colada; src/client.ts restores both during hydration.
src/stores/auth.ts owns session state and route guards depend on auth.user.

API integration

src/api/client.ts is generated by swagger-typescript-api; do not hand-edit generated sections.
API access should go through the generated client and @httpClientAdapter, not raw fetch.
src/api/httpClientAdapter.server.ts handles SSR-side API calls by forwarding request headers/cookies and proxying frontend /r/* requests to https://api.pipic.fun.
src/api/httpClientAdapter.client.ts is the browser-side adapter.

Notable flows

src/stores/auth.ts initializes the logged-in user from /me and opens an MQTT connection after login.
src/composables/useUploadQueue.ts implements the custom upload queue:
- 90MB chunks
- max 3 parallel uploads
- max 3 retries
- max 5 queued items
Styling uses UnoCSS (uno.config.ts).

Important notes

Prefer the actual current code over older documentation when they conflict.
The previous version of this file contained stale route and dependency details; verify against src/routes/index.ts and package.json before assuming old pages or libraries still exist.
Any frontend change that affects API contracts should be checked against the backend repo (../stream.api) as well.

3.1 KiB Raw Blame History