go-react

A React-like frontend framework written in Go, compiled to WebAssembly.

Write frontend web applications in pure Go using React's mental model — functional components and hooks. Your Go code compiles to WASM and runs in the browser. A Vite-inspired dev server provides hot reload for a fast development loop.

Features

• Type-safe components — func(props MyProps) *Node with compile-time checked props via generics
• Built-in component library — 30+ components: Button, Card, Alert, Modal, Toast, Tabs, DataTable, AppShell, Sidebar, FAB, and more
• AI chat components — ChatContainer, UseChat hook, SSE streaming, MockStreamProvider for testing, dark mode, auto-scroll, markdown rendering
• Rich editors — Markdown editor with preview and JSON editor with tree view, raw editor, toolbar, and inline editing
• Enterprise layout system — AppShell, AppHeader, AppFooter, Sidebar with collapse, SearchInput with debounce, FilterBar, Skeleton loading, BusyIndicator
• Form system — Type-safe UseForm hook with validation, connected inputs, three validation modes
• Data fetching — UseFetch, UseQuery (caching, retry, polling), UseMutation (cache invalidation)
• Browser API hooks — UseClipboardAction, UseTimeout, UseInterval, UseWindowSize, UseOnline, UseMediaQuery, UseDocumentTitle, UseIntersection, UseResize, UseConsole with testable mocks
• 83 SVG icons — Pure Go icon functions in 6 tree-shakeable categories
• CSS transitions — Animated mount/unmount with 7 built-in presets
• Dark mode & theming — ThemeProvider, UseTheme hook, system preference detection, localStorage persistence, zero re-renders
• Full hooks system — UseState, UseEffect, UseMemo, UseCallback, UseRef, UseContext, UseReducer
• Virtual DOM with reconciliation — Efficient diffing and patching, keyed list support
• Zustand-style global store — Type-safe reactive state management with UseStore hook
• Client-side router — Path params, nested routes, hash-based and history-based routing
• Type-safe element DSL — el.Div(), el.Button(), etc. — compile-time checked, no JSX
• CSS utility system — Tailwind-inspired gr- prefixed classes with theme tokens and design system
• Error boundaries — Catch render panics with typed fallback components
• Full-stack support — Single-command dev server manages backend + frontend; single binary deployment with embedded WASM frontend via embed.FS
• Testable without a browser — All components testable with go test using an in-memory mock DOM
• Testing library — grtest provides GetByText, Click, Type, snapshot testing
• Vite-inspired dev server — File watching, WASM recompilation, WebSocket hot reload with state preservation
• CLI tool — goreact dev, goreact build, goreact create

Quick Start

# Install the CLI
go install codeberg.org/theosun/go-react/cmd/goreact@latest

# Create a new project
goreact create my-app
cd my-app

# Start the dev server
goreact dev

Open http://localhost:3000 — you have a running Go/WASM app with hot reload.

Full-Stack Quick Start

# Create a fullstack project (Go backend + WASM frontend)
goreact create --fullstack my-app
cd my-app

# Start both backend and frontend with one command
goreact dev
# → Backend on :8081, frontend on :3000, both with hot reload

# Build for production (single binary)
goreact build
./bin/server

📚 Documentation

Getting Started

• Getting Started Guide — Install, create a project, and run your first app in 5 minutes
• Core Concepts — Virtual DOM, render cycle, hooks rules

Batteries Included

• Batteries Overview — Tour of all batteries-included features
• Component Library — 12 foundation UI components
• Markdown Editor & Preview — Markdown parser, preview component, and split-pane editor
• JSON Editor — JSON tree view, raw editor, toolbar, inline editing, and cookbook patterns
• Interactive Components — Modal, Toast, Tabs, Accordion, Dropdown, Tooltip
• Enterprise Components — AppShell, Sidebar, SearchInput, FilterBar, DataTable, Skeleton, BusyIndicator, FAB
• Forms — Type-safe form state, validation, and form-connected inputs
• Data Fetching — UseFetch, UseQuery, UseMutation with caching and retry
• Browser APIs — UseClipboardAction, UseTimeout, UseInterval, UseWindowSize, UseOnline, and more with testable mocks
• Browser API Cookbook — Copy-to-clipboard, debounced search, infinite scroll, responsive layout, and more recipes
• Icons — 83 SVG icons as pure Go functions
• CSS Transitions — Enter/exit animations with 7 built-in presets
• Chat Components — ChatContainer, UseChat hook, streaming, MockStreamProvider, testing guide
• Chat Streaming Architecture — SSE streaming, StreamProvider interface, MockStreamProvider for tests

Guides

• Components & Elements — Element DSL, typed props, children, events
• Hooks Reference — Full API for all hooks
• State Management — Zustand-style stores, selectors, UseStore
• Routing — Hash and history routing, path params
• Error Boundaries — Catch render panics with typed fallbacks
• Full-Stack Guide — Go backend + WASM frontend, dev workflow, single-binary deployment
• Deployment — Static hosting, Docker, reverse proxy patterns
• Testing — grtest queries, interactions, snapshots
• Testing Browser Interactions — MockTimer, MockClipboard, MockWindow, MockObserver patterns
• Theming & Dark Mode — ThemeProvider, dark mode, system preference detection, FOUC prevention

Reference

• CLI Reference — goreact dev, goreact build, goreact create
• Architecture — Framework internals and package structure
• Design System — Color palette, typography, spacing, component style specs
• WASM Loading Indicator — Loading spinner, error state, HMR toast, dark mode, accessibility
• Known Limitations — Current constraints and workarounds

Tutorials

• Examples — Counter, Todo, Showcase, Fullstack, and Batteries walkthroughs
• For React Developers — Map your React knowledge to go-react

Migration

• Migration: Typed Props — Migrate from untyped to typed props
• Migration: Typed Elements — Migrate from untyped to typed element calls
• Migration: Browser APIs — Migrate from raw syscall/js to pkg/browser hooks

Examples

The examples/ directory contains complete applications:

• Counter — Minimal app demonstrating UseState and events
• Todo — Store-based state management with CRUD operations
• Showcase — Multi-page app with routing, store, CSS, and 40+ tests
• Fullstack — Go backend + WASM frontend as a single binary
• Toodoo — Full-stack todo app with SQLite backend, REST API, MockClient testing, and 40+ tests
• Batteries — Comprehensive demo of all batteries-included features: components, forms, data tables, icons, transitions, error boundaries (43 tests)
• Chat — Full-stack AI chat with SSE streaming, markdown rendering, and 20+ tests
• Enterprise — Enterprise dashboard with AppShell, Sidebar, DataTable, SearchInput, and dark mode

# Run an example (frontend-only)
goreact dev --dir ./examples/showcase

# Run the fullstack example
cd examples/fullstack && goreact dev

# Run showcase tests (no browser needed)
go test ./examples/showcase/... -v

Architecture

Downstream App (Go)
     │
     │  func App(props) *Node
     │  hooks, store, router, elements
     ▼
┌──────────────────────────────────────────┐
│  go-react framework (pkg/)               │
│                                          │
│  vdom ──▶ reconciler ──▶ renderer ──▶ DOM│
│  hooks    store    router    css    el   │
└──────────────────────────────────────────┘
     │                          │
  dom/jsdom (WASM)         dom/mock (tests)
     │                          │
  syscall/js              in-memory tree
     │
  Browser DOM

Requirements

• Go 1.24+
• A modern browser with WebAssembly support

Development

goreact dev           # Start dev server with hot reload (frontend-only or fullstack auto-detected)
goreact build         # Build for production (auto-detects project type)
make test             # Run all tests (no browser needed)
make precommit        # fmt + vet + test + build (run before every commit)
make build            # Build CLI tool (for framework development)
make build-wasm       # Build WASM examples (for framework development)

License

[Add license here]