Your first stream
From an empty route to a patched element, and the bytes in between.
Sit. Read. The stream was always yours to bend.
Sarn the Faceless
The smallest useful thing Streamlord does: a request arrives, the server sends HTML for part of the page, and the browser puts it where you said.
The page
Datastar needs to be on the page, and something needs to ask for the stream. This is plain HTML; no build step, no bundle of yours.
<script type="module" src="/static/datastar.js"></script>
<button data-on:click="@get('/feed')">Load the feed</button>
<ul id="feed"></ul>
The route
get("/feed") {
call.respondDatastar {
patchElements(selector = "#feed", mode = ElementPatchMode.APPEND) {
li { +"A new head hangs on the wall" }
}
}
}
respondDatastar opens a Server-Sent Events response, runs your block, and closes when the block
returns. Everything you call inside it writes one frame.
What went over the wire
That route builds one event:
PatchElements(
elements = "<li>A new head hangs on the wall</li>",
selector = "#feed",
mode = ElementPatchMode.APPEND,
)
and this is exactly what the encoder makes of it:
event: datastar-patch-elements
data: selector #feed
data: mode append
data: elements <li>A new head hangs on the wall</li>
That is the whole exchange. The browser appends the <li> to #feed and nothing else on the
page is touched. You will rarely construct a PatchElements yourself, since patchElements { } does
it for you, but it is the thing the protocol carries, and worth seeing once.
Adding state
Elements are half of Datastar. The other half is signals: a small reactive store in the browser that your server can patch in the same stream.
get("/feed") {
call.respondDatastar {
patchElements(selector = "#feed", mode = ElementPatchMode.APPEND) {
li { +"A new head hangs on the wall" }
}
patchSignals("heads" to 13)
}
}
Now <span data-text="$heads"></span> anywhere on the page reads 13, and a button with
data-show="$heads > 0" appears. You never wrote a line of JavaScript, and the server never
learned what the page looks like.
Where to go next
The same feed, three ways further:
- Keep it open. The stream above closes immediately. It does not have to: hand
respondDatastaraFlowand it stays open for as long as the flow produces, which is how you build a counter, a progress bar or a live log. That, the plugin, and reading signals back are on the Ktor page, or Spring WebMVC if that is your realm. - Test it. Testing opens with a test of this very route: it reads the response
back and asserts the
<li>andheadswithout a browser. - Catch the mistakes before they ship. Write
"$heads"in a Kotlin string and Kotlin takes it for itself. The editors mark that as you type, and the analysis fails the build on it in CI. The $ trap explains why it compiles at all.