# Hotwire Patterns > Deep Hotwire (Turbo, Stimulus, Hotwire Native) mental models, decision frameworks, and internals-informed debugging for Rails apps. Use whenever working with Turbo Drive/Frames/Streams, Morphing, ActionCable broadcasting, Turbo Cache, Stimulus controller design, Hotwire Native (iOS/Android, Path Configuration, Bridge Components), system testing Hotwire features, migrating legacy apps to Turbo, or debugging Hotwire behavior. Triggers on "Turbo Frame not updating", "Content missing", "morphing wipes my form", "broadcast not arriving", "flaky system test", "add Hotwire to legacy app", "wrap app with Hotwire Native", or any Turbo/Stimulus/Hotwire design decision. - Skill: `maquina-app/hotwire-patterns` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add maquina-app/hotwire-patterns` - Raw SKILL.md: https://api.skillmd.com/api/skills/maquina-app/hotwire-patterns/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: maquina-app (https://skillmd.com/u/maquina-app) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/maquina-app/hotwire-patterns --- # Hotwire Patterns Internals-informed patterns for building and debugging Hotwire applications. Core philosophy: **enhance the browser, don't reinvent it**. Start by imagining a JS-free, plain-HTML version of every feature, then compose the separate pages into an integrated UI with Turbo. HTML is the source of truth for state, everywhere. ## The escalation ladder (choose the cheapest tool that works) Hotwire is a cost/benefit dial, not a single approach. Escalate only when the previous rung stops being a good tradeoff: 1. **Turbo Drive + Morphing refreshes** — re-render everything server-side; fastest to build. 2. **Turbo Frames** — decompose the page; localize updates without touching the rest. 3. **Turbo Stream actions** — surgical DOM updates; more precise, more maintenance cost. 4. **Stimulus** — small client-side behavior where a server round-trip makes no sense. 5. **Island of reactive framework (React/Vue) or API calls** — only for genuinely high-interactivity widgets (maps, editors). Different parts of one app can sit on different rungs; it all composes. ## Turbo Drive essentials - Drive intercepts link clicks and form submissions, fetches via `fetch`, replaces `` wholesale, and diff-merges `` children (identical nodes untouched → assets not re-parsed; that's the speed win). Order of head children isn't preserved and doesn't matter. - Assets must live in ``. Modern `async` scripts + HTTP/2 remove old reasons for body-bottom scripts. - UJS replacements: `data: {turbo_method: :delete}` for non-GET links; `data: {turbo_confirm: "..."}` for confirm dialogs (works on forms and non-GET links; add `turbo_method: :get` to use on plain links). Customize globally via `Turbo.config.forms.confirm = (message, formEl, submitter) => Promise`. - Submit buttons auto-disable during submission. `turbo:submit-start` / `turbo:submit-end` events carry `event.detail.formSubmission.submitter` — use for loaders. - **Failed form submissions must return 4xx** (`render :new, status: :unprocessable_entity`). Turbo requires a redirect on success; it renders 4xx bodies happily. - `Turbo.visit(location)` is the programmatic navigation entry point; `Turbo.visit(location, { frame })` navigates a frame. - Non-GET links work by Turbo building a hidden form on the fly and submitting it — everything true of forms is true of these links. - Visit types: `advance` (link click), `replace` (redirect after form submit), `restore` (history). This matters for morphing (below). - Link prefetch fires after 100ms hover on plain GET links (no turbo-stream expectation, no confirm dialog). GET idempotency becomes mandatory; the `X-Sec-Purpose: prefetch` header identifies prefetches server-side if you must special-case. ## Turbo Frames Mental model: **a page within a page**. A frame runs the same three observers as Drive (link clicks, non-GET links, form submits) but scoped, and updates only itself. - Links/forms inside a frame load the response, find the frame with the **matching id** in it, and swap only that frame's content. The response page needs the same `turbo_frame_tag` — you don't need to frame the whole target template, just the part you want. - `data-turbo-frame="_top"` on a link/button/form escapes the frame and drives the full page. `target: "_top"` on the frame tag itself makes everything inside escape by default. - Use `dom_id` for frame ids everywhere; `turbo_frame_tag record` uses it under the hood. For "new" records that need per-context frames (e.g., one new-form per kanban column), build custom string ids in a helper — frame ids are global on the page. - Remote frames: `src:` attribute loads content on render (eager) or on scroll into view with `loading: "lazy"`. Great for decomposing heavy pages (dashboards) into independent endpoints — progressive enhancement applied to composition. - Missing frame in the response → console warning + `TurboFrameMissingError` + "Content missing" in the UI. Catch `turbo:frame-missing` to handle it yourself (`preventDefault`), and consider reporting these to error tracking (ignore 5xx statuses — already logged server-side; get status from `event.detail.response.status`). - `data-turbo-permanent` elements (must have unique ids) are transplanted as the same live JS objects across updates — listeners and state survive. - Frame renderer re-runs inline `