README
¶
GoFastr examples
Two kinds of example live here.
Go examples (runnable)
Self-contained Go programs. Run one under the dev server for rebuild-on-save, livereload, and the dev MCP tools your coding agent reads:
cd examples/<name> && gofastr dev # or: go run ./examples/<name>
Every server example binds through isolation.ListenAddr, so $PORT
(injected by gofastr dev and by PaaS runtimes) wins over the example's
default port. TestE2E_DevLoop_Examples in cmd/gofastr boots each one
under gofastr dev and checks it answers on the address the banner
prints. The process module is the exception: it is a stdio child, not a
server, so go run it.
| Example | What it shows |
|---|---|
blog |
Entities in Go + custom endpoints + full-text search; the canonical starter. |
meridian |
The flagship SaaS app (generated, then owned): auth + owner-scoped CRUD, scoped API tokens, and a generated customer CLI under meridian/cmd/meridian. Install it with go install ./examples/meridian/cmd/meridian; docs at gofastr docs app-cli. |
api-tour |
The v2 REST API: includes, cursor pagination, batch, SSE. |
backoffice |
The entity admin (battery/admin) behind a demo login. |
spa |
Client-side navigation over server-rendered islands. |
static-site |
Static page serving with the file server. |
desktop-notes |
The same app as a desktop window (battery/desktop, experimental, macOS today) or over HTTP with --serve: owner-scoped notes, native menu, clipboard and file dialogs through the typed bridge, a plugin capability. |
desktop-focus |
The whole desktop surface in one app (battery/desktop, experimental, macOS today): hidden-title window, floating timer widget, settings window, tray countdown, notifications, deep links, cross-window messages, a focus plugin capability; also over HTTP with --serve. |
gofastr-runs |
A per-user OS service (battery/service, experimental) that tracks every gofastr app running on the machine from the local run registry: a polled web list, a page per run, and MCP tools (runs_list, run_get) that agents reach through gofastr-runs service mcp. |
semantic-demo |
Semantic search with battery/semantic. |
embed-demo |
Embeddable surfaces: an app and a customer's site on two origins. |
processmodule-demo |
A process-isolated third-party module speaking the moduleproto protocol over stdio. The canonical process-module example and the child the go/no-go gate suite drives end to end. |
webmcp-remote-assist |
Authenticated WebMCP + WebRTC remote support: support-only tool discovery, one typed command behind the manual button and the AI tools, role-filtered realtime state, peer-to-peer camera with server-side signaling only. |
rtc-call |
WebRTC rooms the packaged way: battery/rtc signaling (zero hand-rolled relay), anonymous cookie identity through Authorize, the rtc runtime module with one peer connection per peer, peer-to-peer camera plus chat on a negotiated data channel. |
site |
The framework's live component gallery and reference docs site: every UI component rendered one per page, the hosted examples, and the gofastr-plugins registry rendered from a vendored plugins.json (scripts/vendor-plugins-json.sh refreshes it). Run with cd examples/site && gofastr dev. |
team-builder |
Records kept in the visitor's browser: a Pokémon team saved to IndexedDB through framework/localentity (a ui.Form saves, a ui.Grid of cards lists, every tab stays in step), no database and no app JavaScript. |
hn |
A Hacker News reader in the HNPWA shape, for comparing first loads with other frameworks: five ranked lists, story pages with full comment threads, user pages. Synthetic seeded data in SQLite through the entity layer, ui.EntryList and ui.CommentThread, no app CSS beyond its top bar. See hn/README.md. |
layoutlab |
Tree-layout outlets prototype a shell layout with outlets, a route area, and per-screen/group fills. |
App spec examples (declarative)
These are gofastr.yml app specs, no Go. They describe a whole app
(entities, screens, nav, seed) declaratively. Generate a runnable project
from one with:
cd examples/ecommerce && gofastr generate app gofastr.yml
| App spec | Domain |
|---|---|
ecommerce |
The flagship. A complete storefront: 5 related entities, themed UI, custom endpoints, and seed data, declared once in gofastr.yml and emitted as runnable Go. Ships secure-by-default: auth enabled plus owner-scoped orders / order_items. See ecommerce/README.md; flagship_test.go regenerates and boots it end-to-end. |
lms |
Courses, lessons, enrollments. |
portfolio |
Projects + case studies. |
project-manager |
Projects, tasks, teams. |
real-estate |
Listings, agents, inquiries. |
Every app spec here is validated by TestExampleAppSpecsLoad
(cmd/gofastr), so a broken one fails CI.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package main is Acme Tracker's public face: the product's marketing site and help center, built from the layout primitive exactly the way docs/DESIGN-layout-outlets.md's "Ready-made layouts" section draws the site and docs shapes — real pages, real copy, no lab fixtures.
|
Package main is Acme Tracker's public face: the product's marketing site and help center, built from the layout primitive exactly the way docs/DESIGN-layout-outlets.md's "Ready-made layouts" section draws the site and docs shapes — real pages, real copy, no lab fixtures. |
|
helpdocs
Package helpdocs is acme-site's help center page: the article nav on the left, the article in the middle, the table of contents on the right, and a previous/next pager under the article.
|
Package helpdocs is acme-site's help center page: the article nav on the left, the article in the middle, the table of contents on the right, and a previous/next pager under the article. |
|
sitefooter
Package sitefooter is acme-site's colophon, built the way siteheader builds the top bar: plain html elements composed here, the look in sitefooter.style.css (an owned style; `gofastr gen styles` writes the class methods in sitefooter_style.gen.go), and every dimension a theme token.
|
Package sitefooter is acme-site's colophon, built the way siteheader builds the top bar: plain html elements composed here, the look in sitefooter.style.css (an owned style; `gofastr gen styles` writes the class methods in sitefooter_style.gen.go), and every dimension a theme token. |
|
siteheader
Package siteheader is acme-site's top bar, built the way an app builds any piece of chrome the framework does not ship:
|
Package siteheader is acme-site's top bar, built the way an app builds any piece of chrome the framework does not ship: |
|
Package main is a tour of the v2 API surface added to the framework:
|
Package main is a tour of the v2 API surface added to the framework: |
|
Command backoffice is a minimal example of battery/admin rendered through a UI host: a few entities, a (demo-grade) login, and admin.New(...) drawing the whole back office with defaults.
|
Command backoffice is a minimal example of battery/admin rendered through a UI host: a few entities, a (demo-grade) login, and admin.New(...) drawing the whole back office with defaults. |
|
Command desktop-focus is the desktop battery's feature-complete dogfood app: a local-first pomodoro timer that exercises the whole battery/desktop surface (unified-chrome main window over the sidebar material, floating widget, settings window, tray countdown, notifications, deep links, cross-window messages, a plugin capability, the updater) and runs unchanged over plain HTTP behind --serve / --addr / $PORT.
|
Command desktop-focus is the desktop battery's feature-complete dogfood app: a local-first pomodoro timer that exercises the whole battery/desktop surface (unified-chrome main window over the sidebar material, floating widget, settings window, tray countdown, notifications, deep links, cross-window messages, a plugin capability, the updater) and runs unchanged over plain HTTP behind --serve / --addr / $PORT. |
|
Command desktop-notes is the desktop battery's dogfood app: a local-first notes app that runs unchanged inside the OS WebView (desktop.New + Run) or over plain HTTP behind --serve / $PORT.
|
Command desktop-notes is the desktop battery's dogfood app: a local-first notes app that runs unchanged inside the OS WebView (desktop.New + Run) or over plain HTTP behind --serve / $PORT. |
|
Package ecommerce is GoFastr's declaration-driven flagship example: a complete storefront: five related entities, screens, navigation, custom endpoints, seed data, and a theme, declared once in gofastr.yml and emitted as runnable Go by the CLI:
|
Package ecommerce is GoFastr's declaration-driven flagship example: a complete storefront: five related entities, screens, navigation, custom endpoints, seed data, and a theme, declared once in gofastr.yml and emitted as runnable Go by the CLI: |
|
app
command
|
|
|
Package main demonstrates embeddable surfaces: a GoFastr app handing out a piece of itself to a website it does not control.
|
Package main demonstrates embeddable surfaces: a GoFastr app handing out a piece of itself to a website it does not control. |
|
Command gofastr-runs lists every gofastr app running on this machine, from the local run records each App writes when its port opens (framework/localrun), and serves that list to agents over MCP.
|
Command gofastr-runs lists every gofastr app running on this machine, from the local run records each App writes when its port opens (framework/localrun), and serves that list to agents over MCP. |
|
Package main is a Hacker News reader in the HNPWA shape: the same app many frameworks have built, so their first loads can be compared on the same pages.
|
Package main is a Hacker News reader in the HNPWA shape: the same app many frameworks have built, so their first loads can be compared on the same pages. |
|
hnheader
Package hnheader is the reader's top bar: the name and the section links on one strip in the theme's primary colour.
|
Package hnheader is the reader's top bar: the name and the section links on one strip in the theme's primary colour. |
|
Package main is layoutlab, the demo app for the tree-layout outlets prototype.
|
Package main is layoutlab, the demo app for the tree-layout outlets prototype. |
|
Package main is Meridian, the GoFastr flagship demo, and the design-system completeness canary (CLAUDE.md hard rule 9).
|
Package main is Meridian, the GoFastr flagship demo, and the design-system completeness canary (CLAUDE.md hard rule 9). |
|
cmd/meridian
command
meridian is a terminal client for your app's HTTP API, generated by `gofastr generate cli` from the current entity set.
|
meridian is a terminal client for your app's HTTP API, generated by `gofastr generate cli` from the current entity set. |
|
sitefooter
Package sitefooter is Meridian's colophon, built the way siteheader builds the top bar: plain html elements composed here, the look in meridian-sitefooter.style.css (an owned style; `gofastr gen styles` writes the class methods in meridian-sitefooter_style.gen.go), and every dimension a theme token.
|
Package sitefooter is Meridian's colophon, built the way siteheader builds the top bar: plain html elements composed here, the look in meridian-sitefooter.style.css (an owned style; `gofastr gen styles` writes the class methods in meridian-sitefooter_style.gen.go), and every dimension a theme token. |
|
siteheader
Package siteheader is Meridian's top bar, built the way an app builds any piece of chrome the framework does not ship:
|
Package siteheader is Meridian's top bar, built the way an app builds any piece of chrome the framework does not ship: |
|
Package main is the processmodule-demo: a minimal but real third-party module that speaks the moduleproto protocol over stdio.
|
Package main is the processmodule-demo: a minimal but real third-party module that speaks the moduleproto protocol over stdio. |
|
Package main is the dogfood example for battery/rtc: anonymous users, rooms by name, camera and microphone peer to peer, chat over a negotiated data channel.
|
Package main is the dogfood example for battery/rtc: anonymous users, rooms by name, camera and microphone peer to peer, chat over a negotiated data channel. |
|
siteheader
Package siteheader is rtc-call's top bar, built the way an app builds any piece of chrome the framework does not ship:
|
Package siteheader is rtc-call's top bar, built the way an app builds any piece of chrome the framework does not ship: |
|
Package main is a minimal demonstration of the battery/semantic package.
|
Package main is a minimal demonstration of the battery/semantic package. |
|
docpage
Package docpage is the GoFastr site's article shell: the section nav on the left, the article in the middle, with breadcrumbs above the body and a previous/next pager under it, and an optional rail on the right.
|
Package docpage is the GoFastr site's article shell: the section nav on the left, the article in the middle, with breadcrumbs above the body and a previous/next pager under it, and an optional rail on the right. |
|
sitefooter
Package sitefooter is the GoFastr site's colophon, built the way siteheader builds the top bar: plain html elements composed here, the look in docsite-footer.style.css (an owned style; `gofastr gen styles` writes the class methods in docsite-footer_style.gen.go), and every dimension a theme token — the wider spacing step (64px) this page's rhythm needs is docsite-footer.tokens.css's --spacing-section, and the grid sits at the site's wide cap (--size-wide-width, 1240px), the same measure the header and page sections align to.
|
Package sitefooter is the GoFastr site's colophon, built the way siteheader builds the top bar: plain html elements composed here, the look in docsite-footer.style.css (an owned style; `gofastr gen styles` writes the class methods in docsite-footer_style.gen.go), and every dimension a theme token — the wider spacing step (64px) this page's rhythm needs is docsite-footer.tokens.css's --spacing-section, and the grid sits at the site's wide cap (--size-wide-width, 1240px), the same measure the header and page sections align to. |
|
siteheader
Package siteheader is the GoFastr site's top bar, built the way an app builds any piece of chrome the framework does not ship:
|
Package siteheader is the GoFastr site's top bar, built the way an app builds any piece of chrome the framework does not ship: |
|
Package main is the dogfood example for core-ui/localdb and framework/localentity: a Pokémon team builder whose team lives in the visitor's browser.
|
Package main is the dogfood example for core-ui/localdb and framework/localentity: a Pokémon team builder whose team lives in the visitor's browser. |
|
Package main is Acme Tracker, the layout showcase as a real app: a small issue tracker built only from the framework's components and typed theme, where every tree-layout feature appears as ordinary product behaviour — no outlined boxes, no marker strings.
|
Package main is Acme Tracker, the layout showcase as a real app: a small issue tracker built only from the framework's components and typed theme, where every tree-layout feature appears as ordinary product behaviour — no outlined boxes, no marker strings. |
|
appbar
Package appbar is the tracker's application bar, built the way an app builds any piece of chrome the framework does not ship:
|
Package appbar is the tracker's application bar, built the way an app builds any piece of chrome the framework does not ship: |
|
Package main is the reference example for authenticated WebMCP plus WebRTC remote support: one Go binary, one origin, two roles.
|
Package main is the reference example for authenticated WebMCP plus WebRTC remote support: one Go binary, one origin, two roles. |
|
siteheader
Package siteheader is remote assist's top bar, built the way an app builds any piece of chrome the framework does not ship:
|
Package siteheader is remote assist's top bar, built the way an app builds any piece of chrome the framework does not ship: |
Click to show internal directories.
Click to hide internal directories.