The Complete Production SOP: How to Deploy and Run Hotwire Turbo Drive, Frames & Streams Architecture in Autonomous AI Agents

---
name: "turbo-hotwire-html-streaming"
description: "Stream HTML fragment updates over WebSockets and accelerate page navigation with Hotwire Turbo."
metadata:
  author: "Basecamp"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "configure turbo frames"
  - "turbo stream append html"
  - "hotwire turbo drive"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

import * as Turbo from "@hotwired/turbo";

// Initialize Hotwire Turbo globally
Turbo.start();

// Configure global custom headers for fetch/stream requests if necessary
document.addEventListener("turbo:before-fetch-request", (event) => {
  event.detail.fetchOptions.headers["Accept"] = [
    "text/vnd.turbo-stream.html",
    "text/html, application/xhtml+xml",
    event.detail.fetchOptions.headers["Accept"]
  ].filter(Boolean).join(", ");
});

<!-- Valid Turbo Stream Response -->
<turbo-stream action="append" target="chat-messages">
  <template>
    <article id="message_104" class="message-bubble">
      <p>Real-time fragment rendered directly from backend template.</p>
      <time datetime="2026-03-31T09:00:00Z">Just now</time>
    </article>
  </template>
</turbo-stream>

<turbo-stream action="update" target="unread-counter">
  <template>
    <span class="badge">12</span>
  </template>
</turbo-stream>

import { describe, it, expect } from "vitest";

describe("Turbo Stream Fragment Delivery", () => {
  it("delivers correct content-type and template encapsulations", async () => {
    const res = await fetch("http://localhost:3000/messages", {
      method: "POST",
      headers: { Accept: "text/vnd.turbo-stream.html" },
      body: new URLSearchParams({ body: "Deterministic AI Output" })
    });
    expect(res.headers.get("content-type")).toContain("text/vnd.turbo-stream.html");
    const html = await res.text();
    expect(html).toMatch(/<turbo-stream action="(append|prepend|replace)" target="[^"]+">\s*<template>/);
  });
});