OpenParable
Skip to content
← Back to skills

Developing With Turbo Streams

Development
developing-with-turbo-streams

Developing With Turbo Streams is an Agent Skill for development published in the hotwired-laravel/turbo-laravel repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Develops with Turbo Streams for partial page updates and real-time broadcasting. Activates when using turbo_stream() or turbo_stream_view() helpers; working with stream actions like append, prepend, replace, update, remove, before, after, or refresh; using the Broadcasts trait, broadcastAppend, broadcastPrepend, broadcastReplace, broadcastRemove, or broadcastRefresh methods; listening with x-turbo::stream-from; using the TurboStream facade for handmade broadcasts; combining multiple streams; or when the user mentions Turbo Stream, broadcasting, real-time updates, WebSocket streams, or partial page changes.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/hotwired-laravel/turbo-laravel/blob/HEAD/resources/boost/skills/developing-with-turbo-streams/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/developing-with-turbo-streams, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Turbo Streams

Turbo Streams let you change any part of the page using eight actions: append, prepend, replace, update, remove, before, after, and refresh. They work as HTTP responses (after form submissions) and as real-time broadcasts over WebSocket.

HTTP Turbo Streams

Detecting Turbo Stream Requests

Check if the request accepts Turbo Stream responses before returning them:

@verbatim

if ($request->wantsTurboStream()) {
    return turbo_stream($post);
}

return redirect()->route('posts.show', $post);

}

@endverbatim

The turbo_stream() Helper

@verbatim

// Fluent builder (no arguments returns a PendingTurboStreamResponse) return turbo_stream()->append('posts', view('posts._post', ['post' => $post])); return turbo_stream()->prepend('posts', view('posts._post', ['post' => $post])); return turbo_stream()->before(dom_id($post), view('posts._post', ['post' => $newPost])); return turbo_stream()->after(dom_id($post), view('posts._post', ['post' => $newPost])); return turbo_stream()->replace($post, view('posts._post', ['post' => $post])); return turbo_stream()->update($post, view('posts._post', ['post' => $post])); return turbo_stream()->remove($post); return turbo_stream()->refresh();

@endverbatim

Targeting Multiple Elements

Use the *All methods or targets() to target multiple elements by CSS selector:

@verbatim

@endverbatim

Morph Method

Use morph() on replace/update to morph content instead of replacing it:

@verbatim

@endverbatim

Combining Multiple Streams

Pass an array or collection to return multiple stream actions in one response:

@verbatim

@endverbatim

Turbo Stream Views

Render a full Blade view with the Turbo Stream content type. Useful for complex multi-stream responses:

@verbatim

<x-turbo::stream action="update" target="post_count"> {{ Post::count() }} posts </x-turbo::stream>

@endverbatim

The Stream Blade Component

@verbatim

{{-- Target by model (auto-generates DOM ID) --}} <x-turbo::stream action="replace" :target="$post"> @include('posts._post', ['post' => $post]) </x-turbo::stream>

{{-- Multiple targets by CSS selector --}} <x-turbo::stream action="remove" targets=".notification" />

@endverbatim

Broadcasting (Real-Time Streams)

The Broadcasts Trait

Add the Broadcasts trait to your Eloquent model:

@verbatim

class Post extends Model { use Broadcasts; }

@endverbatim

Manual Broadcasting

Call broadcast methods directly on a model instance:

@verbatim

// Broadcast only to other users (exclude current user) $comment->broadcastAppend()->toOthers();

// Queue the broadcast for async processing $comment->broadcastAppend()->later();

@endverbatim

Directed Broadcasting

Broadcast to a specific model's channel:

@verbatim

@endverbatim

Automatic Broadcasting

Enable automatic broadcasts on model lifecycle events:

@verbatim

// Enable auto-broadcasting (broadcasts on create, update, delete)
protected $broadcasts = true;

// Customize insert action (default is 'append')
protected $broadcasts = ['insertsBy' => 'prepend'];

// Specify which model's channel to broadcast to
protected $broadcastsTo = 'post';

// Or define dynamically
public function broadcastsTo()
{
    return $this->post;
}

}

@endverbatim

Page Refresh Broadcasting

Instead of granular stream actions, broadcast a page refresh signal:

@verbatim

// Auto-broadcast page refreshes on model changes
protected $broadcastsRefreshes = true;

}

@endverbatim

This works best with <x-turbo::refreshes-with method="morph" scroll="preserve" /> in the layout.

Listening for Broadcasts

Use the <x-turbo::stream-from> component in your Blade views to subscribe to a channel:

@verbatim

{{-- Public channel — no auth needed --}} <x-turbo::stream-from :source="$post" type="public" />

@endverbatim

Define the channel authorization in routes/channels.php:

@verbatim

Broadcast::channel(Post::class, function ($user, Post $post) { return $user->belongsToTeam($post->team); });

@endverbatim

Handmade Broadcasts (via Facade)

Use the TurboStream facade for broadcasts not tied to a model:

@verbatim

TurboStream::broadcastAppend( content: view('notifications._notification', ['notification' => $notification]), target: 'notifications', channel: 'general', );

TurboStream::broadcastRemove(target: 'notification_1', channel: 'general'); TurboStream::broadcastRefresh(channel: 'general');

@endverbatim

Broadcasting from Response Builder

Chain broadcastTo() on a Turbo Stream response to also broadcast it:

@verbatim

@endverbatim

Global Broadcast Scope

Exclude the current user from all broadcasts in a request:

@verbatim

// In a controller or middleware Turbo::broadcastToOthers();

// Anywhere Turbo::broadcastToOthers(function () { // Turbo Streams broadcasted here will not be delivered to the current user... });

@endverbatim