# Streamlord
> A Datastar toolchain for Kotlin. Datastar lives in strings your compiler never reads. Streamlord checks them in your editor, when the event is built, and before a byte reaches the browser, with adapters for Ktor and Spring.
The SDK speaks the Datastar 1.0.5 Server-Sent Events protocol and is published to Maven Central under `io.github.markusaugust.streamlord`. The editors, a VS Code extension and an IntelliJ plugin, read Datastar as a language wherever it is written and need no part of the SDK.
# Introduction
Source: https://streamlord-docs.netlify.app/introduction/
> A Datastar toolchain for Kotlin: an SDK for Ktor and Spring, assertions for your tests, an analysis for your CI, and two editor extensions.
Streamlord is a [Datastar](https://data-star.dev) toolchain for Kotlin. With Datastar your server
sends HTML and signal patches down one Server-Sent Events connection, and the browser applies
them. There is no client bundle of yours to build, no JSON API to design, and no second model of
your page living in a framework.
Streamlord is four tools, designed together. Adopt one, or all four:
- **The SDK.** Adapters for [Ktor](https://streamlord-docs.netlify.app/ktor/) and [Spring](https://streamlord-docs.netlify.app/spring-webmvc/) over one core that
speaks the Datastar 1.0.5 protocol exactly.
- **Assertions for your tests.** `streamlord-test` reads a response back into the events it
carried, so a [test](https://streamlord-docs.netlify.app/testing/) says what the endpoint meant instead of comparing bytes.
- **The analysis.** Datastar lives inside attribute values and Kotlin strings, where no compiler
looks. [`streamlord-analysis`](https://streamlord-docs.netlify.app/analysis/) reads them, and one test fails the build on a
mistake in CI.
- **The editors.** A [VS Code extension and an IntelliJ plugin](https://streamlord-docs.netlify.app/editors/) run the same analysis
as you type, with the fix a click away.
The last two are the ones no other Datastar library on the JVM has.

That is `dataText("$count")` in VS Code. It compiles, because `count` is a parameter, and it would
send the browser whatever number `count` held instead of the signal `$count`. The editor marks it as an error before you
build, and the quick fix rewrites it to `signal("count")`. The same check runs in IntelliJ, and
[in CI](https://streamlord-docs.netlify.app/analysis/) as a test you add, with no editor at all.
## The same endpoint, twice
One route that adds a line to a list and updates a counter. First by hand, against the protocol:
```kotlin
get("/feed") {
call.response.header("Cache-Control", "no-cache")
call.response.header("X-Accel-Buffering", "no")
if (call.request.local.version == "HTTP/1.1") {
call.response.header("Connection", "keep-alive")
}
call.respondBytesWriter(ContentType.Text.EventStream) {
writeStringUtf8("event: datastar-patch-elements\n")
writeStringUtf8("data: selector #feed\n")
writeStringUtf8("data: mode append\n")
writeStringUtf8("data: elements
A new head hangs on the wall
\n\n")
flush()
writeStringUtf8("event: datastar-patch-signals\n")
writeStringUtf8("data: signals {\"heads\":13}\n\n")
flush()
}
}
```
Then with Streamlord:
```kotlin
get("/feed") {
call.respondDatastar {
patchElements(selector = "#feed", mode = ElementPatchMode.APPEND) {
li { +"A new head hangs on the wall" }
}
patchSignals("heads" to 13)
}
}
```
Both send the same bytes, one event at a time, and the same headers to a request that keeps the
connection open; the headers below say what the first gets wrong on one that asks to close it. The
difference is what the first one leaves to you:
- **Flushing.** Every event needs its `flush()`. Leave one out and the event waits in a buffer
until the next flush or the end of the response, which on a stream that stays open can be
minutes. Streamlord flushes after every event.
- **Markup over several lines.** Every line needs its own `data: elements` prefix. Write
`"data: elements $html\n"` with a newline inside `html`, and every line after the first is
dropped; a blank line inside it ends the event early. Streamlord splits it for you.
- **A mode that needs a selector.** `mode append` without a `selector` line goes out by hand.
Streamlord refuses to build it and throws `DatastarEventValidationException` where the event is
constructed, before a byte of it is written.
- **The JSON.** By hand you write the signals and escape them yourself. Streamlord encodes
`"heads" to 13`, or a data class through a [codec](https://streamlord-docs.netlify.app/signals/).
- **The headers.** `Cache-Control: no-cache` because the specification asks for it,
`X-Accel-Buffering: no` because nginx holds the stream back without it, and
`Connection: keep-alive` on HTTP/1.1 only, because HTTP/2 forbids it, and not to a request
whose `Connection` header asks to close. The version by hand still answers that one with
`keep-alive` on CIO, Netty and Tomcat, where Tomcat sends its own `close` beside it; Jetty
drops the `keep-alive` itself. `respondDatastar` sets all three and reads the protocol version
and the request's own `Connection` itself.
## Three ways to write markup
The DSL above is one of three, and none of them is the real one with the others tolerated beside
it. The same patch inside `respondDatastar`, written each way:
```kotlin
patchElements(selector = "#feed", mode = ElementPatchMode.APPEND) {
li { +"A new head hangs on the wall" }
}
```
```kotlin
patchElements(
"""
A new head hangs on the wall
""",
selector = "#feed",
mode = ElementPatchMode.APPEND,
)
```
```kotlin
patchElements(
pebble.render("feed/head.peb", mapOf("text" to "A new head hangs on the wall")),
selector = "#feed",
mode = ElementPatchMode.APPEND,
)
```
The template tab renders `feed/head.peb`, which holds `
{{ text }}
`. Every entry point
that takes HTML takes a `String`, so a template engine needs no integration: render, then pass
the result. [Choosing a style](https://streamlord-docs.netlify.app/choosing-a-style/) compares them.
## What you get
**Two realms, served without favour.** Ktor is the Sword, Spring is the Shield. Neither is the
port the other was bolted onto: both are adapters over the same core, and Ktor and Spring WebMVC
put identical bytes on the wire.
**An encoder that cannot be talked into lying.** Eight patch modes exist, and every mode except
`outer` and `replace` requires a selector. Streamlord refuses to construct an event the client
would reject, at the point you construct it, rather than letting you discover it in a browser
console.
**Tests that say what the endpoint meant.** `events.assertPatchElements(selector = "#feed", ...)`
checks the event, not the bytes it was written as, and ignores what it did not ask about. It binds
no test framework, and it reads a Ktor test response, a Spring one, or a stream that stays open.
**An analysis that reads what the compiler does not.** The check your editor runs is a library.
Point one test at `src/main/kotlin` and the build fails on an interpolated signal in a file no
editor ever opened.
**Editors that read Datastar as a language.** A VS Code extension and an IntelliJ plugin colour
signals, actions and modifiers inside your Kotlin and your HTML, and say so when a modifier is
misspelled. The code on this site is highlighted by the very same grammars.
## What it costs you
Almost nothing, and that is deliberate. The core carries the Kotlin standard library and
coroutines, and nothing else, not even a JSON library, because it has its own strict RFC 8259
parser and writer. The framework adapters compile against your framework and add no version of
their own. You reach for a codec module only when you want data classes as signals.
```kotlin
dependencies {
implementation("io.github.markusaugust.streamlord:streamlord-ktor:0.23.0")
// Optional: the kotlinx.html DSL, and data classes as signals.
implementation("io.github.markusaugust.streamlord:streamlord-html:0.23.0")
implementation("io.github.markusaugust.streamlord:streamlord-json-kotlinx:0.23.0")
}
```
## What it does not do
It does not render your pages for you, and it has no opinion about how you build HTML beyond
giving you three ways to do it. It does not ship Datastar itself: the client bundle is yours to
include, from a CDN or from your own static files. It does not ship Datastar Pro, and it never
will; the Pro helpers emit the documented attribute names and nothing more, and the bundle and
the licence are yours to bring.
And it does not guess. Where the protocol is ambiguous, Streamlord refuses rather than picks.
> *Every soul in Gallowmark knows my name, and not one knows my face. I took three rubies from
> the Iron Crown of Kell and the land fell apart in my hands. Now I will take one thing from you:
> the belief that the browser must be bought with JavaScript.*
>
> Sarn the Faceless, whom the river-priests of Thurn call the Lord of Streams
---
# Install and modules
Source: https://streamlord-docs.netlify.app/install/
> You need one artifact, two if you want the DSL, three at most. Here is which.
**Most projects take two.** One adapter for your framework, plus `streamlord-html` if you want to
write markup in Kotlin. A third only when you want your signals as data classes.
Start by copying the block for your framework, and read the rest of this page only if you want to
know why.
## Ktor
```kotlin
dependencies {
implementation("io.github.markusaugust.streamlord:streamlord-ktor:0.23.0")
implementation("io.github.markusaugust.streamlord:streamlord-html:0.23.0")
implementation("io.github.markusaugust.streamlord:streamlord-json-kotlinx:0.23.0")
}
```
```xml
io.github.markusaugust.streamlordstreamlord-ktor0.23.0io.github.markusaugust.streamlordstreamlord-html0.23.0io.github.markusaugust.streamlordstreamlord-json-kotlinx0.23.0
```
## Spring Boot 4
```kotlin
dependencies {
implementation("io.github.markusaugust.streamlord:streamlord-spring:0.23.0")
implementation("io.github.markusaugust.streamlord:streamlord-html:0.23.0")
implementation("io.github.markusaugust.streamlord:streamlord-json-jackson:0.23.0")
}
```
```xml
io.github.markusaugust.streamlordstreamlord-spring0.23.0io.github.markusaugust.streamlordstreamlord-html0.23.0io.github.markusaugust.streamlordstreamlord-json-jackson0.23.0
```
That is the whole answer. `streamlord-core` arrives with the adapter, so you never name it.
---
## Can I just take all of them?
No, and it is worth one paragraph to say why.
You would get `streamlord-json-kotlinx`, `streamlord-json-jackson` **and**
`streamlord-json-jackson2`: three JSON libraries doing one job. On Spring that is not merely
wasteful: Jackson 2 and Jackson 3 are different packages, and the wrong codec compiles happily
and then fails at runtime on an `ObjectMapper` that is not the one Spring configured.
You would also get both adapters, one of which has no framework to bind to.
There is no `streamlord-all` for the same reason. A single artifact would have to depend on Ktor
*and* Spring *and* three JSON libraries, and you use one of each at most.
## The three questions
**Which framework?** `streamlord-ktor` or `streamlord-spring`. Take exactly one. It is the only
one you must take, and it brings `streamlord-core` with it.
**How do you write HTML?** Take `streamlord-html` for the kotlinx.html DSL. Skip it if you write
markup as strings or render it from templates. Both work with the adapter alone, and both are
[first-class](https://streamlord-docs.netlify.app/choosing-a-style/).
**Do you want signals as data classes?** Take one codec module. Skip it and the built-in reader
gives you `signals.string("query")` with no dependency at all.
If you answered *framework, no, no*, you take one artifact and you are done.
## Choosing the codec
Only if you answered yes to the third question. Match what your application already has, because
the point of these modules is to reuse the JSON library you have rather than add a second one.
| Codec module | Take it when |
|---|---|
| `streamlord-json-kotlinx` | you already use kotlinx.serialization |
| `streamlord-json-jackson` | Spring Boot 4, which ships Jackson 3 (`tools.jackson`) |
| `streamlord-json-jackson2` | your application already uses Jackson 2 (`com.fasterxml`) |
### What each one puts on your classpath
Resolved from the build, not from memory. `kotlin-stdlib` is left out of all three, and so is
`streamlord-core`, which arrives with your adapter either way.
**`streamlord-json-kotlinx`**
- `org.jetbrains.kotlinx:kotlinx-serialization-json 1.11.0`
- `org.jetbrains.kotlinx:kotlinx-serialization-core 1.11.0`
**`streamlord-json-jackson`**: Jackson 3
- `tools.jackson.core:jackson-databind 3.3.0`
- `tools.jackson.core:jackson-core 3.3.0`
- `com.fasterxml.jackson.core:jackson-annotations 2.23`
**`streamlord-json-jackson2`**: Jackson 2
- `com.fasterxml.jackson.core:jackson-databind 2.23.0`
- `com.fasterxml.jackson.core:jackson-core 2.23.0`
- `com.fasterxml.jackson.core:jackson-annotations 2.23`
Jackson 3 still takes its annotations from the 2.x artifact; that is Jackson's own arrangement,
not something Streamlord does.
### Do we pin your Jackson version?
No. Every dependency is published as a **soft** requirement: `requires` in the Gradle module
metadata, a plain `` in the POM, never `strictly` and never a range. You can always
override it. But soft means different things to the two build tools, and it is worth knowing
which one you are using.
**Maven.** Your BOM wins outright. Spring Boot's `dependencyManagement` beats any version arriving
through a transitive dependency, so the Jackson you get is the Jackson Boot chose, and ours is
ignored.
**Gradle, with `io.spring.dependency-management`.** The same as Maven, and this is the setup
start.spring.io generates. That plugin pins every managed version, downwards as well as upwards,
so the Jackson you get is Boot's. Resolved under Boot 4.0.8, the codec's `jackson-databind 3.3.0`
becomes Boot's `3.1.5`.
**Gradle, with `platform(SpringBootPlugin.BOM_COORDINATES)`.** The highest version wins. A
platform contributes constraints rather than enforcement, so if Boot pins a Jackson older than the
one this release was built against, adding the codec **raises** your Jackson version: the same
build resolves `3.3.0`. If Boot's pin is newer, Boot's wins and nothing changes.
Both were resolved rather than reasoned about, and neither is a surprise you cannot undo:
```kotlin
dependencies {
// Take Boot's Jackson, whatever it is.
implementation("io.github.markusaugust.streamlord:streamlord-json-jackson:0.23.0") {
exclude(group = "tools.jackson.core")
}
}
```
Or pin it yourself, or use `enforcedPlatform` for Boot's BOM. All three work, because nothing on
our side is strict.
### When Boot's Jackson has a known vulnerability
Under Maven and `io.spring.dependency-management`, the Jackson your application runs is Boot's, so
that is the version a scanner such as Sonatype Lifecycle reports, whatever Streamlord asks for. On
27 October 2026 every released Boot pinned a `jackson-databind` with a published advisory:
| Spring Boot | Jackson 3 | Jackson 2 |
| ------------- | --------- | --------- |
| 4.0.8, 4.1.1 | 3.1.5 | 2.21.5 |
| 4.0.9, 4.1.2 | 3.1.7 | 2.21.7 |
| 3.5.16 | | 2.21.4 |
[CVE-2026-68497](https://github.com/advisories/GHSA-q4xh-88c3-wmh7), a denial of service when
reading a `Duration` or an `XMLGregorianCalendar`, is fixed in 3.1.6 and 2.21.6.
CVE-2026-110879, where the type parameters of a generic type id get past the
`PolymorphicTypeValidator` ([jackson-databind#6287](https://github.com/FasterXML/jackson-databind/pull/6287)),
is fixed in 3.1.8 and 2.21.8. Streamlord 0.14.0 asks for 3.2.4 and 2.22.4, which have both fixes,
but under Boot's management that request is ignored.
Raise Boot's own version property, on the minor line Boot is built against. The names differ
between Boot 4 and Boot 3, so take the block for yours.
**Boot 4.** `jackson-bom.version` is Jackson 3 and `jackson-2-bom.version` is Jackson 2; set the
second only if Jackson 2 is on your classpath too. In Maven:
```xml
3.1.82.21.8
```
In Gradle with `io.spring.dependency-management`:
```kotlin
extra["jackson-bom.version"] = "3.1.8"
extra["jackson-2-bom.version"] = "2.21.8"
```
**Boot 3.** There is only Jackson 2, and its property is `jackson-bom.version`. Boot 3 has no
`jackson-2-bom.version`, so setting it changes nothing, and the Boot 4 block above names a Jackson 2
BOM 3.1.8 that does not exist, which fails the build. In Maven:
```xml
2.21.8
```
In Gradle with `io.spring.dependency-management`:
```kotlin
extra["jackson-bom.version"] = "2.21.8"
```
Not `implementation(platform("tools.jackson:jackson-bom:3.1.8"))`: under that plugin the line
resolves to Boot's 3.1.7 and says nothing. With `platform(SpringBootPlugin.BOM_COORDINATES)` you
need none of this on Boot 4, because the codec's 3.3.0 already wins. Each block was resolved and
run, the codec decoding through Boot's own mapper, on Boot 4.1.2 and 3.5.16. Drop the property once
Boot pins a fixed Jackson itself.
Outside Boot's management you run the Jackson Streamlord asks for. Streamlord 0.13.0 and older ask
for 3.2.3 and 2.22.3, which have CVE-2026-110879, so move to 0.14.0.
### And coroutines
Boot pins kotlinx-coroutines the same way: 1.10.2 under Boot 4.0 and 4.1, which is the version
Streamlord is compiled against. A Ktor application resolves a newer one through Ktor and that is
fine too; the Spring adapter's tests run on 1.10.2 and on the newest release.
### In practice you add few new jars
The trees above are what the codec pulls *if nothing else has pulled it already*. On Spring Boot,
Jackson is on your classpath before you add anything of ours, so the codec adds **one small jar**
and the rest resolves to a version already present, possibly bumped, as above. The same goes for
`streamlord-json-kotlinx` in a project that already serializes with kotlinx.
That is the whole reason there are three codec modules instead of one with a JSON library baked
in: the library is yours, and we would rather use it than ship a second copy of it.
**Taking no codec adds nothing at all.** The built-in reader is part of `streamlord-core` and has
its own RFC 8259 parser and writer, and `signals.string("query")` needs no library.
## All ten, for reference
The first law is that Streamlord brings nothing you do not already carry. This column is where
you check that.
| Module | Brings with it |
|---|---|
| `streamlord-core` | `kotlin-stdlib`, `kotlinx-coroutines-core` |
| `streamlord-html` | `kotlinx-html` |
| `streamlord-ktor` | nothing, Ktor is `compileOnly` |
| `streamlord-spring` | nothing, Spring and the servlet API are `compileOnly` |
| `streamlord-json-kotlinx` | `kotlinx-serialization-json` |
| `streamlord-json-jackson` | `jackson-databind` 3 |
| `streamlord-json-jackson2` | `jackson-databind` 2 |
| `streamlord-html-pro` | nothing beyond `streamlord-html` |
| `streamlord-analysis` | nothing beyond `streamlord-core` |
| `streamlord-test` | nothing beyond `streamlord-core`, and no test framework |
**The Soul** is `streamlord-core`: the protocol, the events, the encoder, a strict JSON engine and
the ports. It has no JSON library because it has its own RFC 8259 parser and writer.
**The Sword** is `streamlord-ktor` and **the Shield** is `streamlord-spring`. Neither is the port
the other was bolted onto; both are adapters over the same core, and Ktor and Spring WebMVC put
identical bytes on the wire. On WebFlux the frames are written by Spring's own encoder: the same
fields and the same data, in Spring's spelling.
**The Tongue** is `streamlord-html`: every `data-*` attribute, action and modifier of Datastar
1.0.5 as typed extension functions.
`streamlord-html-pro` is a separate, opt-in artifact for [Datastar Pro](https://streamlord-docs.netlify.app/datastar-pro/). It
contains no Pro code and is inert without the bundle you licensed.
`streamlord-test` is assertions for your tests: it reads a Datastar response back into the
events it carried so a test can say what it means rather than compare the whole body as a string.
It binds no test framework, so it works under kotlin.test, JUnit, Kotest or TestNG alike. Take it
as a `testImplementation` and nowhere else. It is on [Testing](https://streamlord-docs.netlify.app/testing/).
`streamlord-analysis` is the analysis behind the editor tooling: the Kotlin string reader, the
expression and markup rules, the signal and selector collectors. The editors are its first
consumers, and you never need it to write a stream. Take it when you want to run the same checks
yourself, for example over your own sources in CI. See [The analysis](https://streamlord-docs.netlify.app/analysis/).
## What you still have to bring
The Datastar client bundle. Streamlord is the server half; it does not ship, fetch or vendor the
JavaScript, and it has no opinion about whether you take it from a CDN or serve it from your own
static files. **1.0.5** is what this release speaks.
## Versions
JDK 21 builds Streamlord; the artifacts target JDK 17, the oldest realm both Ktor 3 and Spring
Framework 7 still tolerate. Kotlin 2.4 builds it, to the level of Kotlin 2.2, so a project on
Kotlin 2.2 or newer compiles against it; Boot 4.0 manages 2.2, and the documentation's examples are
compiled with 2.2 on every build. The Ktor adapter runs on Ktor 3.0 and newer. Its tests run on
the newest and on 3.0, all but the one for `HttpRequestLifecycle`, which came in 3.4. The Spring
adapter is compiled and tested against Framework 7.0 (Boot 4) on every build. Boot 3 is not
supported.
On Ktor 3.0 with the Netty engine, look at the Netty underneath. `ktor-server-netty` 3.0.0 brings
Netty 4.1.114.Final, which has known vulnerabilities, among them HTTP request smuggling in
`netty-codec-http` ([CVE-2026-33870](https://github.com/advisories/GHSA-pwqr-wmgm-9rr8)) and the
MadeYouReset attack on HTTP/2 ([CVE-2025-55163](https://github.com/advisories/GHSA-prj3-ccx8-p6x4)).
Streamlord brings neither Ktor nor Netty, so the remedy is in your build. Either move to a newer
Ktor (3.6.0 brings Netty 4.2.17.Final), or keep Ktor and raise Netty to the newest 4.1 release,
4.1.140.Final at the time of writing; neither had an advisory against it then. The adapter's
tests on Ktor 3.0 run on that Netty. In Gradle:
```kotlin
dependencies {
implementation(platform("io.netty:netty-bom:4.1.140.Final"))
}
```
In Maven, import the same BOM:
```xml
io.nettynetty-bom4.1.140.Finalpomimport
```
`./gradlew dependencyInsight --dependency netty-codec-http --configuration runtimeClasspath` or
`mvn dependency:tree` shows which Netty you run.
The servlet engines on Ktor 3.0 have the same problem. `ktor-server-tomcat-jakarta` 3.0.0 brings
Tomcat 10.1.30, which has known vulnerabilities, among them an authentication bypass in the DIGEST
authenticator ([CVE-2026-65905](https://github.com/advisories/GHSA-9xv2-5v5q-p794)). Raise it to
the newest 10.1 release, 10.1.61 at the time of writing. Tomcat has no BOM, so in Gradle:
```kotlin
configurations.configureEach {
resolutionStrategy.eachDependency {
if (requested.group.startsWith("org.apache.tomcat") && requested.version?.startsWith("10.1.") == true) {
useVersion("10.1.61")
}
}
}
```
In Maven, list every `org.apache.tomcat` and `org.apache.tomcat.embed` artifact in
`mvn dependency:tree` at that version under ``. Maven raises only what you
name, and `tomcat-catalina` alone brings eleven more, so a partial list mixes two Tomcat versions on
one classpath.
`ktor-server-jetty-jakarta` 3.0.0 brings Jetty 11.0.24. Raising it to 11.0.26 with
`platform("org.eclipse.jetty:jetty-bom:11.0.26")` helps, but Jetty 11 is no longer maintained in
the open, and 11.0.26 is the last release on Maven Central. It still has four advisories, among
them HTTP request smuggling ([CVE-2026-2332](https://github.com/advisories/GHSA-355h-qmc2-wpwf))
and an authority and `Host` mismatch
([CVE-2026-6790](https://github.com/advisories/GHSA-7p3p-8qv8-m2vh)). If you run the Jetty engine
in production, move to Ktor 3.5 or newer, whose Jetty 12 has all four fixed. The adapter's tests
on Ktor 3.0 run on Tomcat 10.1.61 and Jetty 11.0.26.
`streamlord-json-kotlinx` is the one module that can raise your Kotlin standard library. It takes
kotlinx.serialization 1.11.0, which asks for `kotlin-stdlib` 2.3.20, so in a Gradle project on
Kotlin 2.2 the newer one wins:
```text
$ ./gradlew dependencyInsight --dependency kotlin-stdlib --configuration runtimeClasspath
org.jetbrains.kotlin:kotlin-stdlib:2.3.20
Selection reasons:
- By conflict resolution: between versions 2.3.20, 2.2.21 and 2.1.0
```
That does no harm. The Kotlin 2.2 compiler reads a standard library one version ahead, and a
project on 2.2.0 with `allWarningsAsErrors` builds against it without a warning. The other way
round holds too: everything kotlinx.serialization 1.11.0 calls in the standard library is in
2.2.0 already, so it runs on the 2.2 standard library that Maven keeps when you declare it
yourself. Under Spring Boot 4.0 the BOM moves kotlinx.serialization down to 1.9.0, and the codec
runs on that too. To hold Gradle to your own standard library:
```kotlin
dependencies {
implementation("org.jetbrains.kotlin:kotlin-stdlib") {
version { strictly("2.2.21") }
}
}
```
---
# Your first stream
Source: https://streamlord-docs.netlify.app/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.
```html
```
## The route
```kotlin
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:
```kotlin
PatchElements(
elements = "
A new head hangs on the wall
",
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
A new head hangs on the wall
```
That is the whole exchange. The browser appends the `
` 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.
```kotlin
get("/feed") {
call.respondDatastar {
patchElements(selector = "#feed", mode = ElementPatchMode.APPEND) {
li { +"A new head hangs on the wall" }
}
patchSignals("heads" to 13)
}
}
```
Now `` 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
`respondDatastar` a `Flow` and 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](https://streamlord-docs.netlify.app/ktor/) page, or [Spring WebMVC](https://streamlord-docs.netlify.app/spring-webmvc/) if that is your realm.
- **Test it.** [Testing](https://streamlord-docs.netlify.app/testing/) opens with a test of this very route: it reads the response
back and asserts the `
` and `heads` without a browser.
- **Catch the mistakes before they ship.** Write `"$heads"` in a Kotlin string and Kotlin
takes it for itself. [The editors](https://streamlord-docs.netlify.app/editors/) mark that as you type, and
[the analysis](https://streamlord-docs.netlify.app/analysis/) fails the build on it in CI. [The $ trap](https://streamlord-docs.netlify.app/dollar-trap/) explains
why it compiles at all.
---
# The protocol
Source: https://streamlord-docs.netlify.app/protocol/
> Since 1.0, Datastar knows two SSE events. Everything else is built on those two.
> *You were told there were five rites. Whoever told you that read a grimoire from before the
> Ashfall.*
Older documentation speaks of `merge-fragments`, `remove-fragments`, `merge-signals` and
`remove-signals`. Those spells died with 0.x. Since 1.0, Datastar has **two** events.
| Event | What it does | In Streamlord |
|---|---|---|
| `datastar-patch-elements` | Patch complete HTML elements into the DOM | `PatchElements` |
| `datastar-patch-signals` | Merge-patch the signal store, by RFC 7386 | `PatchSignals` |
Removal is not a third event: it is a `PatchElements` with mode `remove`. A signal does not get
deleted either. It is patched to `null`, and RFC 7386 says a null member is a removal.
`ExecuteScript` looks like a third event and is not. The SDK specification defines it as sugar on
top of `patch-elements`: a ``, `` and
`