`:
```html
…
```
There are **two worlds** behind this format, and conflating them is the number one source of confusion.
The first world is an **HTTP response**: the user does something, the server responds with `text/vnd.turbo-stream.html`, the tab applies it. It is synchronous, it lives in the request context, `current_user` exists.
The second is a **broadcast**: a model publishes on an Action Cable channel, every subscribed tab receives it. It is asynchronous, it runs in a job, there is **no request, no session, no `current_user`**. We come back to it below, because that is where the real problems hide.
If you knew Rails before 2021, the first world will ring a bell. Answering a submission with a document that describes DOM mutations is exactly what `create.js.erb` did back in the UJS days. The difference comes down to two points, and they are decisive: the server returns HTML instead of returning JavaScript to evaluate, and the mutation vocabulary is closed at eight actions instead of being "everything jQuery knows how to do". We lost freedom and gained a zero attack surface, an HTTP cache that works, and responses you can read.
### The full path, from controller to view
Here is the canonical server-side form, the one you write in 90% of cases.
```ruby
# app/controllers/invoices_controller.rb
def create
@invoice = Invoice.new(invoice_params)
if @invoice.save
respond_to do |format|
format.turbo_stream # -> create.turbo_stream.erb
format.html { redirect_to @invoice, status: :see_other }
end
else
respond_to do |format|
format.turbo_stream do
render turbo_stream: turbo_stream.replace(
"invoice_form", partial: "invoices/form", locals: { invoice: @invoice }
), status: :unprocessable_entity
end
format.html { render :new, status: :unprocessable_entity }
end
end
end
```
Two ways to respond, and you should choose knowingly. The bare `format.turbo_stream` renders a template, which is the right choice as soon as several zones change. The inline `render turbo_stream:` renders a single action and saves a file, which is the right choice when there really is only one.
The template itself is a plain ERB file that yields the builder:
```erb
<%%# app/views/invoices/create.turbo_stream.erb %>
<%%= turbo_stream.prepend "invoices", @invoice %>
<%%= turbo_stream.update "invoices_count", Invoice.count %>
<%%= turbo_stream.replace "invoice_form" do %>
<%%= render "invoices/form", invoice: Invoice.new %>
<%% end %>
```
Three remarks on those three lines, because they condense almost the whole API.
`turbo_stream.prepend "invoices", @invoice` takes no partial: passing a record is enough, the builder calls `to_partial_path` and renders `invoices/_invoice.html.erb`. That is also why this partial must render an element with `id="<%%= dom_id(invoice) %>"`, without which nothing will be able to target it afterwards.
`turbo_stream.update` accepts a raw string as content, which saves a one-line partial for a counter.
The block form captures whatever you write inside it. Handy, but it is also the one place where it is easy to forget that the content is rendered **outside the page context**, so without the ivars set by some other `before_action`.
And on the calling view side, the rule is the same as everywhere: what the stream aims at must exist with the right `id`.
```erb
<%%# app/views/invoices/index.html.erb %>
<%%= @invoices.count %>
<%%= render @invoices %>
<%%= render "invoices/form", invoice: Invoice.new %>
```
```erb
<%%# app/views/invoices/_invoice.html.erb %>
<%%= invoice.reference %>
<%%= button_to "Supprimer", invoice, method: :delete, form: { data: { turbo_confirm: "Sûr ?" } } %>
```
Note `data-turbo-confirm` on the `button_to` form, the direct successor to rails-ujs' `data-confirm`. The difference is that it is pluggable: `Turbo.config.forms.confirm` accepts your own function, which finally lets you replace the native dialog with your own modal without rewriting the mechanism.
### Eight actions, and `morph` is not one of them
This is the most widespread mistake in the whole ecosystem, including in widely read blog posts.
| Action | What it does | Target required |
|---|---|---|
| `append` | Adds to the end of the target's content | ✓ |
| `prepend` | Adds at the beginning | ✓ |
| `before` | Inserts before the target | ✓ |
| `after` | Inserts after the target | ✓ |
| `replace` | Replaces the target itself | ✓ |
| `update` | Replaces the target's content | ✓ |
| `remove` | Removes the target. No `` | ✓ |
| `refresh` | Triggers a page refresh. No `` | ✕ |
That is all. There is no `morph` action. Morphing is an **attribute**, `method="morph"`, and among the targeted actions **only `replace` and `update` read it**. Writing `turbo_stream.append("x", method: :morph)` does produce the attribute in the HTML, and the JavaScript handler for `append` ignores it purely and simply. `refresh` reads `method` too, but for another reason: to choose the render mode of the page refresh there, broadcast by broadcast.
Two barely documented behaviors:
`append` and `prepend` **deduplicate**: if a direct child of the target carries the same `id` as a top-level incoming element, the old one is removed. `append` therefore behaves like an upsert, which is very handy and never stated. Since 8.0.21, `before` and `after` do the same thing on the target's siblings.
`refresh` can be deduplicated through a `request-id` attribute, the subject of the broadcasts section.
### `target` and `targets` are not the same thing
```ruby
turbo_stream.replace "invoice_42" # target => getElementById
turbo_stream.replace_all ".invoice-row" # targets => querySelectorAll
```
`target` takes a **bare DOM id**, not a selector, and resolves to at most one element. `targets` takes a **CSS selector** and applies the action to every match. If both are present, `target` wins.
On the Ruby side, this difference in kind is absorbed for you. If you pass a record rather than a string, the helper puts the hash in the right place:
```ruby
turbo_stream.replace @invoice # target="invoice_42" <- bare dom_id
turbo_stream.replace_all @invoice # targets="#invoice_42" <- dom_id with the #
```
So the trap only shows up the day you write the selector by hand, because at that point nobody is correcting it any more: `turbo_stream.replace_all "invoice-row"` without the dot or the hash matches nothing, and says nothing.
### The silence when the target does not exist
This is the most expensive behavior in all of Turbo in debugging time.
If `document.getElementById(target)` returns `null`, the getter returns an empty array, and every action iterates over that empty array. **No warning, at any log level.** The stream arrives, it is visible in the Network tab, it is visible in the Rails logs, and nothing happens.
The classic causes: a misspelled or accidentally pluralized `dom_id`, a target living inside a `` or an `
