# Datastar

> Maintain and debug Kubernetto's Datastar server-rendered UI. Use when Codex works on Datastar attributes, signals, SSE handlers, templ-generated fragments, loading indicators, optimistic UI updates, URL/query-string sync, Datastar dependency upgrades, or responsiveness issues in this repository.

- Skill: `hmans/datastar` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add hmans/datastar`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hmans/datastar/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: hmans (https://skillmd.com/u/hmans)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hmans/datastar

---


# Datastar

Use this skill for Kubernetto's Datastar + Go + templ UI. The app is intentionally server-rendered: keep Datastar unless the user explicitly asks for a different architecture.

## Workflow

1. Inspect the local patterns before editing:
   - `internal/server/ui/render.go` for signal attributes and Datastar action attributes.
   - `internal/server/ui/page.templ` for page layout, Datastar script loading, and fragment roots.
   - `internal/server/server.go` for `datastar.ReadSignals`, `datastar.NewSSE`, signal patches, and element patches.
   - `frontend/src/app.js` for URL sync and small optimistic UI helpers.
   - `frontend/src/app.css` for loading and pending states.
2. For detailed implementation patterns, read `references/kubernetto-patterns.md`.
3. When upgrading Datastar, verify current releases/changelogs from official sources before editing versions. Browser package tags and `datastar-go` module versions can move independently.
4. Keep signal names stable in Go JSON structs and JavaScript URL state. In HTML attributes, use kebab-case for camelCase signal names because browsers lowercase attribute names.
5. Prefer Datastar-native loading behavior:
   - Add `data-indicator:loading` to the element initiating the request.
   - Bind visible UI to `$loading` with `data-show`, `data-class`, or similar reactive attributes.
6. Patch normalized server state back to the client before patching affected elements when handlers can canonicalize resource, namespace, selection, sort, or detail signals.
7. Regenerate and verify:
   - `mise x -- go generate ./...`
   - `mise x -- pnpm build:assets`
   - `mise x -- go test ./...`
   - `mise run build` when preparing a final branch/PR.

## Guardrails

- Do not treat `page_templ.go` or `assets/dist/*` as source of truth. Edit `*.templ`, `frontend/src/*`, and Go sources, then regenerate.
- Do not add a client framework for problems Datastar already handles: partial updates, loading indicators, simple optimistic state, or signal-driven requests.
- Keep SSE fragments rooted by stable IDs so Datastar can merge them predictably.
- Keep URL sync in `frontend/src/app.js` compatible with server-normalized signals.
- Add tests around rendered attributes and SSE event bodies when changing signal names, request handlers, or loading-state hooks.