# Datastar Tao > Use when building hypermedia-driven web applications, server-rendered UIs, or any frontend where the backend should own state. Use when choosing between SPA and server-driven architecture. Use when reviewing frontend code for unnecessary client-side state, optimistic updates, or client-side routing. Triggers on requests involving SSE, HTML-over-the-wire, DOM morphing, HTMX, Datastar, signals, or backend-first frontend design. - Skill: `danmestas/datastar-tao` (Agent Skill) - Install (CLI): `npx skillmds@latest add danmestas/datastar-tao` - Raw SKILL.md: https://api.skillmd.com/api/skills/danmestas/datastar-tao/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: danmestas (https://skillmd.com/u/danmestas) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/danmestas/datastar-tao --- # The Tao of Datastar Principles from the [Datastar](https://data-star.dev/) project's philosophy for building maintainable, high-performance web applications. The central thesis: **"The backend is the source of truth. The frontend is a projection of it."** Every architecture decision must be judged by whether it keeps state on the server, leverages the platform, and avoids reinventing what the browser already does well. ## Core Principles ### 1. Backend Owns State Most state belongs on the server. The frontend is exposed to the user — it can be tampered with, fall out of sync, or lose context on refresh. The backend is the single source of truth for application state. **Client-heavy (bad):** ```typescript // Frontend manages its own "truth" — duplicates backend logic, // drifts on stale data, breaks on refresh const [users, setUsers] = useState([]); const [filters, setFilters] = useState({ role: "admin", active: true }); const [sortBy, setSortBy] = useState("name"); const [page, setPage] = useState(1); // Now you need: sync logic, cache invalidation, optimistic rollback, // conflict resolution, offline handling... const filteredUsers = useMemo(() => users .filter(u => u.role === filters.role && u.active === filters.active) .sort((a, b) => a[sortBy].localeCompare(b[sortBy])) .slice((page - 1) * 20, page * 20), [users, filters, sortBy, page] ); ``` **Server-owned (good):** ```go // Backend computes the view, sends the result as HTML func handleUsers(w http.ResponseWriter, r *http.Request) { role := r.URL.Query().Get("role") users := db.GetUsers(role, "active", "name", 1) // Template renders the final HTML — one source of truth tmpl.Execute(w, users) } ``` ```html
``` ### 2. Start with the Defaults The default configuration exists because it covers the majority of use cases. Before changing a default, ask: "Am I solving a real problem, or am I guessing about a future one?" Most custom configurations are premature optimization or cargo-culting from SPA patterns that don't apply. ### 3. Patch, Don't Replace Since the backend owns truth, it drives the frontend by patching — adding, updating, and removing HTML elements and signals. Send the minimal change, not the entire page. The server knows what changed; let it tell the client exactly what to update. **Full replacement (bad):** ```typescript // Replaces entire container — destroys scroll position, focus, // animations, and any transient UI state container.innerHTML = await fetch("/users").then(r => r.text()); ``` **Targeted patch (good):** ```html
Active
``` ### 4. Use Signals Sparingly Signals (reactive client-side state) are the escape hatch, not the default. Overusing signals means you're rebuilding a state manager on the frontend — the exact problem backend-first architecture avoids. **Good uses of signals:** - Toggling element visibility (accordion, dropdown) - Binding form inputs before submission - Transient UI state that has no business meaning (hover, focus) **Bad uses of signals:** - Filtering, sorting, or paginating data client-side - Caching server responses - Duplicating business logic that belongs on the server **Rule of thumb:** If the signal's value would matter after a page refresh, it belongs on the backend. ### 5. In Morph We Trust DOM morphing (updating only the parts of the DOM that actually changed) is the key enabler. It lets you send large HTML fragments — even the entire page — without losing scroll position, focus state, CSS transitions, or form input. This is what makes "just send HTML" viable at scale. Morphing means you don't need: - Virtual DOM diffing - Component-level re-rendering - Key-based reconciliation - Manual DOM manipulation Send the HTML. The morpher handles the rest. ### 6. SSE for Reads, HTTP for Writes (CQRS) Separate read and write channels. Use Server-Sent Events (SSE) as a single long-lived connection for receiving updates from the backend. Use standard HTTP requests for writes. ``` ┌─────────┐ SSE (reads) ┌─────────┐ │ │ ◄──────────────────────────── │ │ │ Browser │ │ Server │ │ │ ──── POST/PUT/DELETE ────────► │ │ └─────────┘ (writes) └─────────┘ ``` **Why this works:** - One persistent connection for all real-time updates - Zero to N events per SSE response — patch elements, patch signals, execute scripts - Writes are standard HTTP — simple, cacheable, debuggable - No WebSocket complexity, no bidirectional protocol to manage ### 7. Compression is Your Superpower HTML + SSE + Brotli compression achieves ratios of 200:1 or higher. Repetitive HTML structures (tables, lists, repeated components) compress spectacularly. This means "send more HTML" is often cheaper on the wire than "send JSON and reconstruct on the client." Don't optimize by sending less HTML. Optimize by enabling compression and sending the right HTML. ### 8. Use Your Templating Language Your backend language already has a templating system. Use it. Keep your rendering DRY with partials, layouts, and components on the server side. Don't build a second component system on the frontend. **Two component systems (bad):** ```typescript // Server renders a shell, client renders components // Now you maintain two template systems, two data flows const UserCard = ({ user }) => (

{user.name}

{user.role}

); ``` **One component system (good):** ```go // Server renders everything — one system, one source of truth {{ define "user-card" }}

{{ .Name }}

{{ .Role }}

{{ end }} ``` ### 9. Don't Reinvent the Browser **Page navigation:** Use `` tags. The browser has handled navigation for 30 years. Client-side routing is a complexity tax you pay to solve problems the browser already solved. **Browser history:** The browser tracks history automatically. The moment you manage history yourself (pushState, replaceState, custom back-button handling), you're adding complexity that fights the platform. **Forms:** Use `
` elements. They handle validation, submission, accessibility, and keyboard interaction out of the box. **Scroll, focus, viewport:** These are browser-managed state. Don't track them in your application state. ### 10. Honest UIs Over Optimistic Updates Optimistic updates show the user a lie — "this succeeded" before it actually has. When the backend disagrees, you need rollback logic, conflict resolution, and error recovery that's harder to build correctly than the optimistic update itself. **Dishonest (bad):** ```typescript // Show success immediately, pray the server agrees const handleLike = () => { setLiked(true); // Lie to user setCount(count + 1); // Lie harder api.like(postId).catch(() => { setLiked(false); // Awkward rollback setCount(count); // Hope state is consistent toast.error("Failed"); // User already scrolled away }); }; ``` **Honest (good):** ```html ``` Use loading indicators to show the user that an action is in progress. Confirm success only when the backend confirms it. ### 11. Accessibility is Non-Negotiable The web should be accessible to everyone. A backend-first architecture has a natural advantage: server-rendered HTML is inherently more accessible than client-rendered JavaScript. But you still need to: - Use semantic HTML (`