Menu
Socka + Durable Object WebSockets—defineSocka, SockaWebSocketDO, useSockaSession, SSR-safe ws URLs, web worker forwarding, live-draft vs commit, canvas/whiteboard acceptance, and pre-merge checks. Use for realtime features, /api/ws, or @firtoz/socka.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Add or change a Durable Object worker package under durable-objects/ (Alchemy, env.d.ts, Hono on the DO). Use when scaffolding with turbo gen durable-object, editing durable-objects/*/alchemy.run.ts, workers/app.ts, or env.d.ts for a DO. Not for web app bindings or cross-worker rpc—see cf-web-alchemy-bindings and cf-worker-rpc-turbo.
Wire @internal/web to durable-objects workers—workspace dep, alchemy.run.ts ReactRouter bindings, and env patterns. Use when adding `workspace:*` for a worker, editing apps/web/alchemy.run.ts, or debugging missing worker types after a new package.
workers/rpc.ts for WorkerRef or DO RPC types, package exports, cross-worker type imports without Turbo cycles, and root dev/destroy wiring. Use when adding WorkerRef, WorkerStub, workers/rpc.ts, turbo circular dependency warnings, or a new app missing from root bun run dev.
Alchemy + env files — repo-root `.env.local` (dev), `.env.staging` (staging / PR preview deploys), `.env.production` (prod / CI), optional per-package `.env.local`, and package-local Alchemy apps. Use when adding secrets or non-secret vars or debugging missing env in local dev. Never use a plain `.env` file. `.env.example` is human documentation only — no script reads it for all keys.
Component organization patterns for React applications. Use when creating components, organizing files, or structuring routes. ALWAYS keep 1 component per file and routes simple.
Guide for creating new Agent Skills when patterns emerge or improvements are needed. Use when encountering repeated patterns, making the same mistakes, discovering better approaches, or receiving user corrections. Covers keeping each skill small (one topic), when to split SKILL.md or add references/, and line-count heuristics.
| name | cf-socka-realtime |
| description | Socka + Durable Object WebSockets—defineSocka, SockaWebSocketDO, useSockaSession, SSR-safe ws URLs, web worker forwarding, live-draft vs commit, canvas/whiteboard acceptance, and pre-merge checks. Use for realtime features, /api/ws, or @firtoz/socka. |
Rule of thumb: Prefer @firtoz/socka and a shared contract package; do not hand-roll { t: "…" } JSON protocols unless the user explicitly wants raw WebSockets. See cf-realtime-websockets.mdc.
| Piece | Where |
|---|---|
defineSocka contract (calls + pushes) | packages/chat-contract/src/contract.ts |
DO extending SockaWebSocketDO | durable-objects/chatroom-do/workers/chatroom-do.ts |
Web worker: upgrade → DO /websocket | apps/web/workers/app.ts |
Client useSockaSession + URL from current host | apps/web/app/components/chat/ChatClient.tsx |
Route-safe wss:// / ws:// builder | apps/web/app/lib/chat-ws-url.ts |
After bunx turbo gen durable-object: the default template is Hono + optional WebSocket forwarding; for Socka + DO SQLite, copy the chatroom pattern (chatroom-do + @internal/chat-contract) and renames described in project-init/SKILL.md for forks. A dedicated Socka codegen path may be added later.
window, window.location, or build wss:// in loaders, actions, or component render on paths that run under SSR.const url = new URL(window.location.href);
url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
url.pathname = "/api/your/prefix/room-id";
// …search params as needed
Do not use fake fallbacks like ws://127.0.0.1/... to satisfy a hook. If a hook needs a URL immediately, mount a child component only after the client has a real URL, or show a loading shell until then.
Match exactly the path prefix handled in apps/web/workers/app.ts before React Router (and do not break Vite HMR upgrades).
For drawing apps, separate:
sendDraft / push draftUpdated (in-progress stroke, uncommitted).applyOp / push opApplied after commit (persisted, undo stack, etc.).Optionally batch or throttle cursor/presence on its own channel so it does not fight stroke traffic. This avoids “nothing appears until mouseup” for remote users.
For interactive canvas features, expect (unless scoped otherwise):
Testing: fetch and unit tests do not catch pointer bugs. Prefer browser automation (e.g. Cursor cursor-ide-browser MCP or Playwright): pointer down / move / up on the canvas, then assert visual or DOM/canvas state. See multiworker-workflow/SKILL.md for when typecheck is not enough.
Socka send.* returns promises. In hot paths (pointer move, requestAnimationFrame, intervals), handle rejections so browser tests and users do not see uncaught promise errors:
void send.sendCursor(...).catch(() => undefined);
defineSocka); no ad-hoc JSON wire protocol unless justified.window / document in SSR render paths for WebSocket URLs.localhost / 127.0.0.1 / placeholder WebSocket URLs as runtime fallbacks.bun run typegen (if routes/bindings changed), bun run typecheck, bun run lint from repo root per multiworker-workflow/SKILL.md.