# 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. ![VS Code with dataText("$count") underlined in red, and the hover: Kotlin interpolates $count here; the browser will never see a signal. Write signal("count").](../../assets/editor-dollar-trap.png) 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.streamlord streamlord-ktor 0.23.0 io.github.markusaugust.streamlord streamlord-html 0.23.0 io.github.markusaugust.streamlord streamlord-json-kotlinx 0.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.streamlord streamlord-spring 0.23.0 io.github.markusaugust.streamlord streamlord-html 0.23.0 io.github.markusaugust.streamlord streamlord-json-jackson 0.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.8 2.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.netty netty-bom 4.1.140.Final pom import ``` `./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 `` after that, or to the end of the page if no `-->` comes. In Chrome, `