datastar-go

name

datastar-go

description

Use this skill whenever the user mentions Datastar, datastar-go, Go + SSE UI updates, `data-*` attributes, backend-driven interactivity, hypermedia UI, or wants to build/debug/refactor a Go web app toward Datastar. Refresh local sources from the official docs and repos, ground answers in the current Datastar docs plus `datastar-go`, prefer backend-driven HTML/SSE over SPA habits, and fix morphing, signals, patching, and SSE mistakes the Datastar way.

datastar-go

Goal

Build and debug Datastar idiomatically in Go, using current official docs and repos.

First steps

1. For any non-trivial Datastar task, refresh the local source cache with bash ~/.agents/skills/datastar-go/scripts/update_sources.sh.
2. Read references/mental-model.md.
3. Read references/go-patterns.md for implementation work.
4. Read references/common-mistakes.md for debugging and refactors.
5. Use references/sources.md to know which local cache paths and upstream URLs matter.

If the bundled script is inconvenient, fetch the official docs directly and inspect the official repos manually.

Source priority

1. .cache/datastar-docs/docs.md
2. .cache/datastar-go-sdk-repo/
3. .cache/datastar-framework-repo/
4. Official Datastar site/repo URLs from references/sources.md

Prefer official sources over blog posts or invented patterns.

Working defaults

• Treat Datastar as backend-driven hypermedia, not as React-lite.
• Treat the server as the source of truth.
• Prefer patching elements for UI/content.
• Use signals for small reactive client state, not as the main application state store.
• Keep data-* expressions short.
• If logic grows, move it to the backend or an isolated script/web component.
• Validate everything on the backend.
• Treat signals as user-controlled input.

Go defaults

• Default import: github.com/starfederation/datastar-go/datastar
• For streams, start with sse := datastar.NewSSE(w, r).
• Use SDK helpers instead of hand-writing SSE when possible.
• Read incoming signals with datastar.ReadSignals(...).
• For one-shot updates, plain text/html or application/json responses are acceptable if they are clearer than SSE.

Push back on these patterns

• Keeping most app state in frontend signals
• Recreating SPA state management on top of Datastar
• Solving Datastar problems with large custom frontend JS blobs
• Embedding large async flows inside data-on or other expressions
• Trusting hidden inputs or signals for auth, authorization, or business rules

Debugging order

1. Check response type: text/html, application/json, or text/event-stream.
2. If patching elements, confirm the target top-level IDs already exist.
3. If using SSE, confirm event formatting and blank-line separators.
4. Check signal names and casing.
5. Check whether the bug is really HTML, escaping, backend state, or invalid assumptions.
6. Simplify toward a smaller Datastar shape before adding more machinery.

Delivery rules

• If implementing: produce idiomatic Go + Datastar code.
• If debugging: identify root cause first, then the smallest fix.
• If refactoring: explain the simpler Datastar shape before rewriting.
• Cite the local cache path or official URL when behavior is subtle or likely to have changed.