datapages

Writing a Datapages Application

You write Go application logic and templates. Datapages generates the server. Follow these steps in order. Do not skip steps.

For the full specification of all parameters, return types, supported field types, and configuration options, see SPECIFICATION.md.

Datapages apps use two other technologies. This skill does not teach them. Learn them separately.

• Templ (github.com/a-h/templ) - Go HTML templating. Handlers return datapages.Component. You write .templ files that compile to Go via templ generate. Datapages does not run this automatically — you must run templ generate yourself after creating or modifying .templ files. Docs: https://templ.guide/developer-tools/llm/
• Datastar (github.com/starfederation/datastar-go/datastar) - Frontend reactivity via HTML attributes and SSE. Actions go into data-on:<event> attributes (data-on:click, data-on:submit). The hyphen form is reserved for plugins (data-on-intersect, data-on-interval, data-on-signal-patch). Docs: https://data-star.dev See also: datastar/SKILL.md

Architecture

• Hypermedia-First (MPA): This is a multi-page application architecture. The backend drives the UI by sending HTML fragments, signal updates, and real-time events over SSE. There is no separate REST API layer - all interactions happen through Datastar SSE streams managed by Datapages.
• Morphing & Patching: Datastar uses morphing to update the DOM - it compares the incoming HTML fragment with the existing DOM and applies minimal changes, preserving focus, scroll position, and CSS transitions. Prefer HTML fragment patches (morphs) over signal updates because morphs carry both structure and data, keeping the server as the single source of truth. Use signal updates only for lightweight, transient UI state (e.g. toggling a loading spinner, updating a counter) where re-rendering HTML would be wasteful. "Fat morphs" - sending a larger HTML fragment that includes surrounding context - are often simpler and more robust than trying to surgically update individual elements. Often a single template per page that renders the entire body is the best approach because it reduces complexity and avoids coordinating multiple partial updates.
• Backend Reactivity: The server renders HTML and manages application state. The frontend is a thin reactive layer that responds to backend updates. The backend determines what the user can do by controlling DOM patches, maintaining a single source of truth.
• Simplicity First: Keep Datastar expressions simple - complex logic belongs in backend handlers or external scripts. Use a "props down, events up" pattern: pass data into functions via arguments, return results or dispatch custom events. State that makes sense to keep on the client (e.g. UI toggles, form input) should be realized using client-side signals, state that should be persisted or shared should live on the server, and state necessary for actions should be communicated via signals.
• No JavaScript: Avoid solving problems with JavaScript. All application logic belongs in Go on the server. Datastar's declarative attributes (data-on, data-bind, data-show, etc.) and signal expressions handle the frontend. Only reach for JavaScript when there is genuinely no other way — e.g. clipboard access, focus management, or interfacing with a third-party browser API that Datastar cannot express.