OpenCode Web

A modern web interface for OpenCode - an AI coding assistant that runs locally. Built with React 19, deployed to Cloudflare Workers edge network.

🎯 What is This?

OpenCode Web is a chat-based web UI for interacting with OpenCode, providing:

• 💬 Real-time streaming responses via Server-Sent Events (SSE)
• 🔄 Live message updates as the AI types
• 🎨 Rich message rendering with markdown, code blocks, reasoning, and tool calls
• 📱 Mobile-first responsive design with drawer navigation
• 🌓 Dark mode support with system preference detection
• 🔌 Direct connection to your local OpenCode server

The app connects to OpenCode running on your machine and provides a polished chat interface for code assistance, file editing, and project management.

🚀 Technology Stack

Frontend

• React 19 - Modern UI library with cutting-edge features
• Vite - Lightning-fast build tooling and dev server
• TanStack Query - Powerful data fetching and caching
• Tailwind CSS v4 - Utility-first CSS framework
• shadcn/ui - High-quality, accessible component library
• AI Elements - Pre-built AI chat UI components
• Storybook 9 - Component development and documentation

Backend

• Hono - Ultralight, modern backend framework
• Cloudflare Workers - Edge computing platform for global deployment
• OpenCode SDK - Official TypeScript SDK for OpenCode API

Real-time & State Management

• Server-Sent Events (SSE) - Real-time message streaming from OpenCode
• React Query Cache - In-place message updates for instant UI feedback
• Type-safe event handling - Fully typed SSE events from OpenCode SDK

📐 Architecture

Dual-Context Build System

Three separate TypeScript contexts:

1. React App (src/react-app/) - Client-side chat interface
2. Worker (src/worker/) - Cloudflare Workers backend (Hono API + SSE proxy)
3. Shared Code (src/components/, src/lib/, src/hooks/) - Reusable UI and utilities

The Worker serves the React app as static assets and proxies API requests to your local OpenCode server.

Real-time Streaming Architecture

OpenCode Server → Worker (SSE Proxy) → Browser (EventSource) → React Query Cache → UI

1. OpenCode emits events - message.updated, message.part.updated, session.idle
2. Worker proxies SSE - Forwards events from OpenCode to browser
3. Browser receives events - useOpencodeEvents hook manages EventSource connection
4. Cache updates in-place - Pure functions update React Query cache directly
5. UI re-renders - React automatically updates when cache changes

Type Safety

All types derived from OpenCode SDK:

• Message, Part, Event types from @opencode-ai/sdk/client
• Custom MessageWithParts interface matching API responses
• Type guards for safe event handling: isMessageUpdatedEvent, isTextPart, etc.
• Zero any types in production code

Path Aliases: All imports use @/* → src/:

import { Button } from "@/components/ui/button"
import { useOpencodeEvents } from "@/hooks/use-opencode-events"
import { upsertMessage } from "@/lib/message-cache-utils"

Getting Started

Prerequisites

1. OpenCode - Install and run OpenCode locally: opencode.ai
2. pnpm - Package manager:

   npm install -g pnpm

Installation

pnpm install

Development

Start the development server:

pnpm dev

Your app will be available at http://localhost:7777.

OpenCode Connection Modes

By default, local development connects to the OpenCode server running on your machine (localhost:4096). The pnpm dev command automatically starts the OpenCode CLI for you.

If you want to run OpenCode inside a sandboxed container instead:

1. Open the Settings drawer in the web UI
2. Create a new Workspace
3. The system will spin up a Cloudflare Container with its own OpenCode instance
4. Select the new workspace to route all requests to the containerized OpenCode

This is useful for testing in an isolated environment that mirrors the production deployment.

Component Development

Start Storybook for isolated component development:

pnpm storybook

Storybook will be available at http://localhost:6006.

Project Structure

src/
├── react-app/          # React application entry and pages
│   ├── pages/          # Page components (ChatPage, etc.)
│   └── *.test.ts       # Test files
├── components/         # Reusable UI components
│   ├── ui/             # shadcn/ui components
│   ├── ai-elements/    # AI chat UI components
│   └── chat/           # Chat-specific components
├── hooks/              # React hooks
│   ├── use-opencode.ts              # API queries and mutations
│   ├── use-opencode-events.ts       # SSE connection management
│   ├── use-streaming-updates.ts     # Real-time cache updates
│   └── opencode-event-utils.ts      # Event parsing utilities
├── lib/                # Utility functions
│   └── message-cache-utils.ts       # Pure cache update functions
├── types/              # TypeScript types
│   ├── opencode-events.ts           # SSE event types
│   ├── opencode-messages.ts         # Message types
│   └── opencode-schemas.ts          # Zod schemas
├── worker/             # Cloudflare Workers backend
│   └── index.ts        # Hono API + SSE proxy
└── stories/            # Storybook stories

Code Quality

Testing

Run all tests:

pnpm test

Run individual test suites:

pnpm test:worker     # Backend/API tests
pnpm test:ui         # React component unit tests (41 tests)
pnpm test:storybook  # Storybook visual/interaction tests

Type Checking

pnpm check

Runs TypeScript compiler in dry-run mode across all contexts.

Linting

pnpm lint

Component Development Workflow

1. Check existing components - Review src/components/ and Storybook
2. Search AI Elements - Check aielements.com for chat UI components
3. Search shadcn/ui - Check ui.shadcn.com for general components
4. Add component:

   pnpm dlx shadcn@latest add <component>
   pnpm dlx ai-elements@latest add <component>

5. Create story - Always add Storybook story for new components
6. Write tests - Add tests to src/react-app/
7. Run tests - pnpm test:ui and pnpm test:storybook

Production Deployment

Build for production:

pnpm build:production

Deploy to Cloudflare Workers:

pnpm deploy