datapages

README

Datapages

🧪 Alpha Software: Datapages is still in early development 🚧.
APIs are subject to change and you may encounter bugs.

A Templ + Go + Datastar web framework for building dynamic, server-rendered web applications in pure Go.

Focus on your business logic, generate the boilerplate Datapages parses your app source package and generates all the wiring. Routing, sessions and authentication, SSE streams, CSRF protection, HTML form and file upload handling, type-safe URL and action helpers, Prometheus metrics - so your application code stays clean and takes full advantage of Go's strong static typing and high performance.

No matter whether you're building real-time collaborative dynamic web app or simple HTMX-style websites - Datapages will serve you well.

Examples

• counter — Minimal real-time counter. Bare bones starting point.
• fancy-counter — Fancy real-time collaborative counter.
• auth-basics — Login/logout with in-memory sessions and CSRF. Bridges the gap between counter and classifieds.
• todolist — Real-time collaborative todo list with per-tab server-side state (Most Tao conform example).
• calculator — Hybrid calculator app that runs both as a multi-client server and single-client Desktop app.
• classifieds — Full-featured classifieds marketplace with sessions, auth, Prometheus metrics, Grafana dashboards and load testing.
• tailwindcss — Minimal static page demonstrating Tailwind CSS integration.
• webcomponents — Landing page with vanilla and Lit-based Web Components bundled via esbuild through a custom watcher.

Getting Started

Install

go install github.com/danmestas/datapages@latest

Initialize New Project

datapages init

For a step-by-step walkthrough from zero to a working interactive app, see GETTING_STARTED.md.

CLI Commands

Command	Description
datapages init	Initialize a new project with scaffolding and configuration.
datapages gen	Parse the app model and generate the datapages package.
datapages watch	Start the live-reloading development server.
datapages lint	Validate the app model without generating code.
datapages version	Print CLI version information.

Configuration

Datapages reads configuration from datapages.yaml or datapages.yml in the module root. If both files exist, the CLI treats that as an error.

The default scaffold created by datapages init looks like this:

app: app
gen:
  package: datapagesgen
  prometheus: true
cmd: cmd/server
watch:
  exclude:
    - ".git/**" # git internals
    - ".*"      # hidden files/directories
    - "*~"      # editor backup files

Optional sections can be added as needed:

assets:
  url-prefix: /static/
  dir: ./app/static/

These top-level keys are supported:

• app: path to the app source package. Default: app
• gen.package: path to the generated package. Default: datapagesgen
• gen.prometheus: enable Prometheus metric generation. Default: true
• cmd: path to the server command package. Default: cmd/server
• assets: embedded static asset serving configuration
• watch: development server settings

When assets is set, both fields are required. url-prefix must start and end with / and cannot be /.

When gen.prometheus is set to false, the generated server code will not include Prometheus imports, metric variables, or the WithPrometheus server option. Use datapages init --prometheus=false to scaffold a project without Prometheus.

The optional watch section configures the development server (host, proxy timeout, debounce, TLS, compiler flags, logging, custom watchers, etc.).

Documentation

• GETTING_STARTED.md — Step-by-step guide to your first app.
• QUICK_REFERENCE.md — One-page cheat sheet for handler signatures, naming conventions, struct tags, and common gotchas.
• EVENT_GUIDE.md — How the event system works: public, private, and signal-scoped events with dispatch patterns.
• DEPLOYMENT.md — Production builds, Dockerfile, Docker Compose, reverse proxy config, and horizontal scaling.
• SPECIFICATION.md — Full source package specification: handler signatures, parameters, return values, events, sessions, and modules.
• FAQ.md — Frequently asked questions and troubleshooting.

Modules

Datapages ships pluggable modules with swappable implementations:

• SessionManager[S]
  • natskv - NATS KV store with AES-128-GCM encrypted cookies
  • inmem - In-memory sessions (lost on restart; single-instance only)
• MessageBroker
  • natsjs - NATS JetStream backed message broker
  • inmem - In-memory fan-out message broker (single-instance only)
• TokenManager
  • hmac - HMAC-SHA256 with BREACH-resistant masking
• TokenGenerator
  • sesstokgen - Cryptographically random session tokens (256-bit)

Motivation

The reason I built Datapages is that the combination of Datastar + Go + Templ is my preferred way of writing server-centric web applications. But in every project I used this tech stack for I kept repeating the same code patterns and solving the same problems over and over again. I realized many developers are repeating the same patterns too and struggle with the common pitfalls:

• How to handle SSE streams correctly?
• How to use NATS effectively?
• How to approach security and authentication?
• How to configure a convenient hot-reload for development?
• How to keep the code maintainable over time, especially when you add more developers and/or AI assistants?
• How to achieve optimal performance and a good UX for endusers?

Datapages allows you to start quickly and jump straight into building your application providing both a Datastar Tao oriented default with examples and enough flexibility to go beyond if you need to.

• datapages lint can be used in CI/CD workflows for extensive static code analysis.
• datapages gen generates all boilerplate code consistently, runs lint too and guides your AI coding agents.
• datapages watch opens interactive hot-reload environment for fast a feedback loop with error reporting directly in the browser.

This tooling also allows LLM coding agents to be more effective at using this tech stack, by consistently guiding it on to the right path when it drifts.

Who This Is For

Datapages is a good fit if you:

• Already write your backend in Go and want to build your web frontend in the same language and toolchain.
• Are building a server-rendered application, where the server owns the data; not a local-first offline-capable SPA.
• Already use Datastar and want a Go framework to help you ship faster with less code while preserving maintainability.
• Already use Templ and want a full framework built around it.
• Use HTMX, idiomorph and Alpine.js, and instead want a single cohesive stack with a smaller bundle size and less spaghetti-code.
• Don't want to maintain a separate REST/GraphQL API just to feed your frontend.
• Want to deploy as a single, statically compiled binary that makes the most of your hardware.
• Want to develop hybrid desktop apps in Go and HTML5 (see Calculator example)

Contributing

See CLAUDE.md for code style, testing conventions, commit message format, and project structure.

Use the example/classifieds/ application as a real-world test fixture when developing Datapages.