FluxyChat Docs

Use the scoped CLI. Bare npx create-fluxy-chat is a different package and 404s.

Hosted app

npx @fluxy-chat/create-fluxy-chat@latest my-app --mode hosted -y

That writes a Vite chat app. After pnpm setup:hosted you sign in on fluxychat.com.

Gallery

Each example needs VITE_FLUXYCHAT_WORKER_URL plus a pk_ (VITE_FLUXYCHAT_PUBLISHABLE_KEY), a public room id (guest), or a member JWT. Open two tabs for anything collaborative.

Zero-backend public room: FluxyRealtimeProvider + publishableKey (pk_, POST /tokens/anonymous). Guest session still works:

<FluxyRealtimeProvider workerUrl={workerUrl} publishableKey={pk}>
  <Chat />
</FluxyRealtimeProvider>

npx @fluxy-chat/create-fluxy-chat@latest my-cursors --example live-cursors
npx @fluxy-chat/create-fluxy-chat@latest my-cursors-chat --example live-cursors-chat
npx @fluxy-chat/create-fluxy-chat@latest my-vanilla --example javascript-live-cursors
npx @fluxy-chat/create-fluxy-chat@latest my-doc --example tiptap-room
npx @fluxy-chat/create-fluxy-chat@latest my-board --example whiteboard
npx @fluxy-chat/create-fluxy-chat@latest my-draw --example draw
npx @fluxy-chat/create-fluxy-chat@latest my-comments --example comments-board
npx @fluxy-chat/create-fluxy-chat@latest my-polls --example polls
npx @fluxy-chat/create-fluxy-chat@latest my-war --example war-room
npx @fluxy-chat/create-fluxy-chat@latest my-iot --example iot-panel
npx @fluxy-chat/create-fluxy-chat@latest my-deal --example deal-room
npx @fluxy-chat/create-fluxy-chat@latest my-fleet --example fleet-panel
npx @fluxy-chat/create-fluxy-chat@latest my-game --example game-tick
npx @fluxy-chat/create-fluxy-chat@latest my-stage --example voice-stage

Cursors travel as WebSocket type: "cursor". Tiptap and the whiteboard sync Yjs on the same room. See What to build for the idea-to-example map.

Three ways to run

Path	Command	You provide
Hosted	`--mode hosted -y`	Clerk on fluxychat.com after setup
Self-host	clone the repo, `pnpm --filter @fluxy-chat/worker dev`	Worker URL + project JWT
SDK-only	`--template react` or `--example` from the gallery	Worker URL + JWT or public room

Env vars (browser)

VITE_FLUXYCHAT_WORKER_URL: hosted API or wrangler dev
VITE_FLUXYCHAT_PUBLISHABLE_KEY: pk_ on FluxyRealtimeProvider (public rooms)
VITE_FLUXYCHAT_MEMBER_JWT + VITE_FLUXYCHAT_ROOM_ID: member
VITE_FLUXYCHAT_PUBLIC_ROOM_ID: guest via FluxyChatClient.joinPublicRoomAsGuest

Keep fc_… API keys on the server.

useChat({ roomId }) is the room session: messages, presence, cursors (sendCursor / liveCursors), broadcast (sendClientEvent), agents (invokeAgent). Yjs is a second binary socket on the same Durable Object.

For cursors only, useLiveCursors({ roomId }). Do not mount both unless they share sessionScope, or you open two sockets.

Need	API
Who is here, pointers, selections	`sendCursor`, `liveCursors`, `useMyPresence` / `presence_patch`
One-shot stamps	`sendClientEvent` (`client-ephemeral-*` skips webhooks)
Shared document	`useStorage` / `FluxyYjsProvider` (`@fluxy-chat/sdk/yjs`)
Activity logs	`useFeeds`, `/rooms/:id/feeds`
Side-panel assistant	`RegisterAiKnowledge` + `<AiChat />`
Pinned review comments	`useThreads`, `/comment-threads`
Chat timeline	`useChat` messages; replies use `parentId`
Nested chat thread	`useThread({ threadParentId })`; registry `GET /rooms/:id/threads`
Agent on the timeline	`invokeAgent`

JWT mint (server)

POST {WORKER}/auth/token with X-Fluxy-Api-Key: fc_… and body { userId, roles, ttlSeconds }. Pass the JWT as FluxyRealtimeProvider authTokenProvider. Nest FluxyYjsProvider inside it, or pass token / authTokenProvider. Details: Choose your path and the auth cookbook.

Open two tabs

Cursors, presence, and chat need a second client on the same roomId. One tab is not a collab test.

CLI and examples