Abstract:

This document is a "Getting Started" guide for Datastar, a lightweight frontend framework designed for creating backend-driven, interactive user interfaces with a hypermedia-first approach. It combines the backend reactivity of frameworks like htmx with the frontend reactivity of Alpine.js, operating without any npm packages or other dependencies. The guide outlines Datastar's core mechanics, which are centered on using declarative data-* HTML attributes for event handling and frontend logic. It details how the backend can manipulate the DOM by "patching" (morphing) HTML elements in response to standard HTTP requests or via real-time Server-Sent Events (SSE), ensuring efficient updates while preserving state.

Datastar: A Guide to Backend-Driven Frontend Development

• Core Philosophy: Datastar is a lightweight frontend framework designed to build interactive, backend-driven UIs using a hypermedia-first approach. It blends backend reactivity (like htmx) with frontend reactivity (like Alpine.js) without requiring npm or other dependencies.
• Simple Installation: To get started, Datastar can be added to a project with a single <script> tag pointing to a CDN or a self-hosted file.
• Declarative data-* Attributes: At its core, Datastar uses data-* HTML attributes to add reactivity. The data-on-click attribute, for example, attaches an event listener to an element and executes a JavaScript expression when triggered.
• Backend-Driven DOM Patching: The framework enables the backend to control the frontend by patching (adding, updating, or removing) HTML elements. It uses a "morphing" strategy by default, which intelligently updates only the modified parts of the DOM to preserve state and improve performance.
• Triggering Backend Requests: Frontend elements can initiate backend communication using Datastar actions. The @get('/endpoint') action sends a GET request to a URL; if the response is HTML, Datastar will morph the returned elements into the DOM based on matching IDs.
• Real-time Updates with SSE: In addition to standard HTTP requests, Datastar supports Server-Sent Events (SSE). The backend can push a continuous stream of datastar-patch-elements events to the client over a long-lived connection, enabling real-time UI updates.
• Developer Tooling: Development is supported by a VSCode extension and an IntelliJ plugin for autocompletion of data-* attributes. A browser-based "Datastar Inspector" is also available to monitor incoming SSE events.
• Backend SDKs: To simplify implementation, Datastar provides SDKs (example shown for Go) that help backend code generate the correctly formatted SSE patch events.