datastar

go-datastar

DataStar protocol library for Go. Every patch is a first-class value that produces an sse.Event — so you can store, queue, filter, replay, and broadcast them through go-sse's transport infrastructure.

Built on go-sse.

What is this?

DataStar is a hypermedia framework that uses Server-Sent Events to push DOM patches, signal updates, and script execution from server to browser. go-datastar provides the Go server-side protocol vocabulary.

The key design principle: patches are values, not method calls. Every patch implements Patch interface { Event() sse.Event }, so you can construct one without an open connection, hand it to a Broadcaster[T], persist it in an EventStore, or filter it through a SubscribeFilter.

Comparison with the official SDK

The official Go SDK, starfederation/datastar-go, is the first-party reference implementation and a perfectly good choice for straightforward request/response handlers. go-datastar exists because of one architectural decision — and everything else follows from it.

Compared against datastar-go v1.2.2, the current release. Upstream release check 2026-11-07: v1.2.2 is the newest Go SDK tag (the repo publishes tags, not GitHub Release objects); the embedded JS bundle pins the upstream datastar v1.0.4 client.

The core difference: patches are values

In the official SDK, every patch is a method on a ServerSentEventGenerator bound to a live http.ResponseWriter. You cannot construct a patch without an open connection:

sse := datastar.NewSSE(w, r)                   // requires the ResponseWriter
err := sse.PatchElements("<div>Update</div>")  // written to the wire immediately

In go-datastar, a patch is a value you can build anywhere and route anywhere:

patch := datastar.NewElementsPatch("<div>Update</div>",
    datastar.WithSelectorID("feed"),
    datastar.WithModePrepend(),
)

evt := patch.Event()        // an sse.Event — store it, filter it, broadcast it
broadcaster.Broadcast(evt)  // fan out to every connected client
store.Append(evt)           // replay it when a client reconnects

Both libraries emit the exact same DataStar wire format. The difference is what you can do with a patch before it hits the network.

Feature comparison

Where the official SDK wins

Honesty first:

• Built-in SSE compression — gzip, Brotli, Zstd, and Deflate with client- or server-priority negotiation. go-datastar leaves compression to the HTTP layer (a reverse proxy does this best); a working gzip middleware pattern ships in example/sse_middleware.go.
• Fewer environment constraints — works on Go 1.24+ with standard tooling. go-datastar requires Go 1.27.1+ (GOEXPERIMENT=jsonv2 is no longer needed under Go 1.27).
• First-party cadence — the reference implementation, tracking DataStar client releases day one.

When to choose which

Choose the official SDK for single-connection request/response handlers where you want the reference implementation, minimal constraints, or built-in compression.

Choose go-datastar when patches are part of your application's state: live feeds and dashboards (broadcast), replay on reconnect (event store), per-user event filtering, machine-readable error handling, or E2E-tested DataStar handlers.

Learn DataStar

New to DataStar itself? The DataStar site hosts the interactive playground and the full client documentation — the wire protocol this library speaks is defined there.

Requirements

• Go 1.27.1+ (v0.6.1 raised the floor; encoding/json/v2 is available without any experiment under Go 1.27, so the old GOEXPERIMENT=jsonv2 prefix is no longer needed)

go build ./...
go test ./... -race -count=1

Install

go get github.com/larsartmann/go-datastar

Optional sub-modules (separately versioned):

go get github.com/larsartmann/go-datastar/static        # embedded JS client bundle (zero deps)
go get github.com/larsartmann/go-datastar/datastartest  # E2E test helpers for consumer handlers
go get github.com/larsartmann/go-datastar/broadcast     # SSE fan-out + replay + hub sharing

Quick start

Patches as values — broadcast to many connections

This is the core pattern that distinguishes go-datastar from the upstream SDK. Construct a patch without a connection, then broadcast it:

broadcaster := sse.NewBroadcaster[sse.Event]()

patch := datastar.NewElementsPatch("<div>Update</div>",
    datastar.WithSelectorID("feed"),
    datastar.WithModePrepend(),
)

// Every subscriber receives the same sse.Event
broadcaster.Broadcast(patch.Event())

Single-request response — fluent builder

For the common case of sending patches on a single HTTP connection, Response wraps a stream and provides fluent methods:

func handler(w http.ResponseWriter, r *http.Request) {
    stream := sse.NewStream(w, r)
    defer func() { _ = stream.Close() }()

    resp := datastar.NewResponse(stream)

    if err := resp.PatchElements("<div>Hello</div>", datastar.WithSelector("#feed")); err != nil {
        log.Printf("patch elements: %v", err)
        return
    }

    if err := resp.MarshalAndPatchSignals(map[string]any{"count": 1}); err != nil {
        log.Printf("patch signals: %v", err)
    }
}

Serve the DataStar JS client

mux.Handle("GET /datastar.js", datastar.ScriptHandler())

In page templates, render the tag with datastar.ScriptTagVersioned("/datastar.js") — the same URL plus the pinned ?v= cache-busting parameter, so a browser cannot serve a stale client after an upgrade (see Serving the JS client).

Fan out patches to many connections

The optional broadcast submodule turns patch values into a live SSE endpoint (fan-out, reconnection replay, hub sharing):

broadcaster := broadcast.NewBroadcasterWithReplay(128)
mux.Handle("GET /events", broadcaster)

broadcaster.Broadcast(datastar.NewElementsPatch("<div>Update</div>",
    datastar.WithSelectorID("feed"),
))

Full working example

A complete live-feed application is in example/:

go run ./example/
# Open http://localhost:8765

Core concept: the Patch interface

type Patch interface {
    Event() sse.Event
}

Four types implement this interface. Everything else is a convenience constructor:

Patches as values in a domain architecture

Because patches are values, your domain layer can produce them without an HTTP connection: map domain events to []Patch in one bridge function, then send, store (replay), or broadcast the events anywhere. A working miniature — domain events → EventBridge → broadcaster + MemoryStore — lives in example/domain-adapter/.

Patch constructors

Elements

Signals

Pre-encoded JSON? Construct directly: datastar.SignalsPatch{Signals: []byte("{\"count\":1}")}.

Script execution

Printf-style variants

WithSelectorf, NewRedirectfPatch, NewConsoleLogfPatch — same behavior with fmt.Sprintf formatting.

Options

Elements

WithSelector, WithSelectorID, WithSelectorf, WithMode, WithNamespace, WithViewTransitions, WithViewTransitionSelector, WithElementsEventID, WithElementsRetryDuration

Mode sugar: WithModeOuter, WithModeInner, WithModeRemove, WithModeReplace, WithModePrepend, WithModeAppend, WithModeBefore, WithModeAfter

Namespace sugar: WithNamespaceHTML, WithNamespaceSVG, WithNamespaceMathML

Signals

WithOnlyIfMissing, WithSignalsEventID, WithSignalsRetryDuration

Script

WithScriptAutoRemove, WithScriptAttributes, WithScriptAttributeKVs, WithScriptEventID, WithScriptRetryDuration

Custom events

WithCustomEventSelector, WithCustomEventBubbles, WithCustomEventCancelable, WithCustomEventComposed, WithCustomEventEventID

Response builder

Response wraps an sse.Stream for single-connection patching. Every method returns error:

Convenience constructors:

• NewResponse(stream) — wrap an existing stream
• NewResponseFromHTTP(w, r) — create stream + response in one call
• ErrorResponse(stream, message, code) — signals patch with error info
• ErrorResponseFromError(stream, err) — signals patch with errorfamily metadata extracted from a Go error (code, family, retryable, httpStatus)
• NotificationResponse(stream, message, kind) — signals patch with notification

Inbound: reading signals

var signals struct {
    Email string `json:"email"`
}
if err := datastar.ReadSignals(r, &signals); err != nil {
    log.Printf("read signals: %v", err)
}

• ReadSignals(r, &target) — extracts signals from ?datastar= query param (GET/DELETE) or JSON body (all other methods). Returns nil if no signals present.
• LastEventID(r) — extracts the last event ID from the Last-Event-ID header or lastEventId query param (for SSE reconnection replay).

HTTP helpers

DataStar action attribute strings for use in HTML:

datastar.GetSSE("/api/feed")
datastar.PostSSE("/api/items/%d", id)
datastar.PutSSE("/api/settings")
datastar.PatchSSE("/api/merge")
datastar.DeleteSSE("/api/items/%d", id)

Serving the JS client

Event store (reconnection replay)

MemoryStore is an in-memory ring buffer implementing sse.EventStore. It keeps the last N events so reconnecting clients can replay missed patches:

store := datastar.NewMemoryStore(128) // keep last 128 events

// In your producer:
store.Append(patch.Event())

// go-sse uses it for automatic replay on reconnection.

For multi-instance deployments, implement sse.EventStore against a shared backend (Redis, Postgres).

Testing your handlers

The datastartest subpackage provides E2E test helpers that parse SSE responses and decode DataStar datalines into typed values — so you can assert on patches without hand-rolling wire-format parsing:

import "github.com/larsartmann/go-datastar/datastartest"

func TestFeedHandler(t *testing.T) {
    events := datastartest.Collect(t, myHandler)
    datastartest.RequireEventCount(t, events, 2)

    // Elements: typed accessors decode the datalines
    datastartest.RequireElements(t, events[0], "#feed", "append", "<div>hello</div>")

    // Signals: unmarshal JSON into a struct
    var data struct{ Count int `json:"count"` }
    _ = events[1].UnmarshalSignals(&data)
}

POST requests

For POST/PUT/PATCH handlers with request bodies, use CollectPost or CollectWithRequest:

// POST with JSON body (most common pattern)
events := datastartest.CollectPost(t, handler, `{"name":"alice"}`)

// Or any method with custom content type
events := datastartest.CollectWithRequest(t, handler, http.MethodPut, body, "application/json")

Streaming handlers

For handlers that keep the connection open (e.g., broadcasting), use CollectN to read exactly N events, or CollectWithTimeout for a time-bounded read:

// Read exactly 3 events then close
events := datastartest.CollectN(t, streamingHandler, 3)

// Or read everything within a deadline (defensive against hung handlers)
events := datastartest.CollectWithTimeout(t, handler, 5*time.Second)

Script patches

Script patches (ExecuteScript, Redirect, ConsoleLog, etc.) wrap JS in <script> tags. Use IsScript() and ScriptContent() to extract and assert on the JavaScript:

events := datastartest.Collect(t, handler)

if events[0].IsScript() {
    js := events[0].ScriptContent() // "console.log('hello')"
}

Search helpers

When a handler sends multiple patches, use FindElement and FindSignals to locate specific events without indexing by position:

evt, ok := datastartest.FindElement(events, "#header")
sigEvt, ok := datastartest.FindSignals(events)

Error handling

Every error returned by go-datastar is a classified *errorfamily.Error carrying a stable code, a behavioral family, and structured context.

Three ways to handle errors

// 1. By code (stable string):
if errorfamily.Code(err) == datastar.CodeSignalsMarshalFailed { ... }

// 2. By sentinel (errors.Is matches by code+family):
if errors.Is(err, datastar.ErrEventNameRequired) { ... }

// 3. By family (behavioral — retryable? whose fault?):
if errorfamily.Classify(err) == errorfamily.Transient { /* backoff + retry */ }

Families

Error codes

Wire format parity

go-datastar reproduces the exact DataStar wire format expected by the DataStar JavaScript client. Mode outer is never emitted (default). Namespace html is never emitted (default). Retry is emitted only when it deviates from the 1000ms default. Data-line construction order, script wrapping, and signal splitting all match the upstream SDK. wire_golden_test.go pins the exact SSE bytes of every patch family — any golden change is a deliberate wire-format change.

Documentation

Consumer guides under docs/:

• docs/architecture.md — the three-layer architecture (transport → protocol → domain) with a diagram and file map
• docs/migration-starfederation.md — migrating from the official SDK (method mapping, gains, tradeoffs)
• docs/ci-watch.md — promote/drop/verify runbook for the non-required CI workflows
• docs/replay.md — MemoryStore + Last-Event-ID reconnection
• docs/error-system.md — the three error-matching dimensions, codes + families
• docs/wire-format.md — annotated datalines per patch family
• docs/testing.md — datastartest quick start, fuzzing, coverage story
• docs/performance.md — measured benchmark table
• docs/migration-guide.md — v0.2.0 → v0.3.0 upgrade guide
• docs/static-js.md — embedded JS pinning + upgrade process

Companion libraries

• go-sse — SSE transport (Stream, Broadcaster, EventStore, Replay, Heartbeat)
• go-error-family — structured error classification

License

MIT