Tombatron.Turbo.SourceGenerator 1.0.0-alpha.3

Tombatron.Turbo

Hotwire Turbo for ASP.NET Core with SignalR-powered real-time streams.

Features

• Turbo Frames: Partial page updates with automatic Turbo-Frame header detection
• Turbo Streams: Real-time updates via SignalR with targeted and broadcast support
• Source Generator: Compile-time strongly-typed partial references
• Minimal API Support: Return partials from Minimal API endpoints with TurboResults
• Simple Architecture: Check for Turbo-Frame header, return partial or redirect
• Zero JavaScript Configuration: Works out of the box with Turbo.js

Installation

NuGet (ASP.NET Core server package):

dotnet add package Tombatron.Turbo

NuGet (Source generator for strongly-typed partials, optional):

dotnet add package Tombatron.Turbo.SourceGenerator

npm (JavaScript client library):

npm install @tombatron/turbo-signalr

Quick Start

1. Add Turbo Services

// Program.cs
builder.Services.AddTurbo();

2. Use Turbo Middleware

// Program.cs
app.UseRouting();
app.UseTurbo();
app.MapRazorPages();
app.MapTurboHub(); // For Turbo Streams

3. Add Tag Helpers

@* _ViewImports.cshtml *@
@addTagHelper *, Tombatron.Turbo

4. Create a Turbo Frame with a Partial

Create a partial view for your frame content:

<turbo-frame id="cart-items">
    @foreach (var item in Model.Items)
    {
        <div>@item.Name - @item.Price</div>
    }
</turbo-frame>

Use the partial in your page:

<h1>Shopping Cart</h1>
<partial name="_CartItems" model="Model" />

5. Handle Frame Requests in Your Page Model

public class CartModel : PageModel
{
    public List<CartItem> Items { get; set; }

    public void OnGet()
    {
        Items = GetCartItems();
    }

    public IActionResult OnGetRefresh()
    {
        Items = GetCartItems();

        // For Turbo-Frame requests, return just the partial
        if (HttpContext.IsTurboFrameRequest())
        {
            return Partial("_CartItems", this);
        }

        // For regular requests, redirect to the full page
        return RedirectToPage();
    }
}

6. Link to the Handler

<turbo-frame id="cart-items" src="/Cart?handler=Refresh">
    Loading...
</turbo-frame>


<a href="/Cart?handler=Refresh" data-turbo-frame="cart-items">
    Refresh Cart
</a>

Turbo Streams (Real-Time Updates)

Send Updates to a Stream

public class CartController : Controller
{
    private readonly ITurbo _turbo;

    public CartController(ITurbo turbo)
    {
        _turbo = turbo;
    }

    [HttpPost]
    public async Task<IActionResult> AddItem(int itemId)
    {
        // Add item to cart...

        // Send update to the user's stream
        await _turbo.Stream($"user:{User.Identity.Name}", builder =>
        {
            builder.Update("cart-total", $"<span>${cart.Total}</span>");
        });

        return Ok();
    }
}

Broadcast to All Connected Clients

// Send updates to every connected client
await _turbo.Broadcast(builder =>
{
    builder.Update("active-users", $"<span>{count}</span>");
});

Render Partials in Streams

Use the async overload to render Razor partials directly in stream updates:

await _turbo.Stream($"room:{roomId}", async builder =>
{
    await builder.AppendAsync("messages", "_Message", message);
});

With the source generator, you get strongly-typed partial references:

await _turbo.Stream($"room:{roomId}", async builder =>
{
    await builder.AppendAsync("messages", Partials.Message, message);
});

Include the Client Script

<script type="module" src="https://cdn.jsdelivr.net/npm/@hotwired/turbo@8/dist/turbo.es2017-esm.min.js"></script>
<script src="_content/Tombatron.Turbo/dist/turbo-signalr.bundled.min.js"></script>

Subscribe to Streams in Your View

<turbo stream="notifications"></turbo>


<turbo-stream-source-signalr stream="user:@User.Identity.Name" hub-url="/turbo-hub">
</turbo-stream-source-signalr>

<div id="cart-total">$0.00</div>

Stream Actions

await _turbo.Stream("notifications", builder =>
{
    builder
        .Append("list", "<div>New item</div>")    // Add to end
        .Prepend("list", "<div>First</div>")      // Add to beginning
        .Replace("item-1", "<div>Updated</div>")  // Replace element
        .Update("count", "42")                     // Update inner content
        .Remove("old-item")                        // Remove element
        .Before("btn", "<div>Before</div>")       // Insert before
        .After("btn", "<div>After</div>");        // Insert after
});

Minimal API Support

Use TurboResults to return partials from Minimal API endpoints:

app.MapGet("/cart/items", (HttpContext ctx) =>
{
    if (ctx.IsTurboFrameRequest())
    {
        return TurboResults.Partial("_CartItems", model);
    }
    return Results.Redirect("/cart");
});

Source Generator

The Tombatron.Turbo.SourceGenerator package scans your _*.cshtml partial views at compile time and generates a Partials static class with strongly-typed references:

// Generated from _Message.cshtml with @model ChatMessage
public static PartialTemplate<ChatMessage> Message { get; }
    = new("/Pages/Shared/_Message.cshtml", "Message");

Use them for compile-time safety instead of magic strings:

await builder.AppendAsync("messages", Partials.Message, message);

Configuration

builder.Services.AddTurbo(options =>
{
    options.HubPath = "/turbo-hub";
    options.AddVaryHeader = true;
});

Helper Extensions

Check if a request is a Turbo Frame request:

if (HttpContext.IsTurboFrameRequest())
{
    return Partial("_MyPartial", Model);
}

// Or check for a specific frame
if (HttpContext.IsTurboFrameRequest("cart-items"))
{
    return Partial("_CartItems", Model);
}

// Or check for a prefix (dynamic IDs)
if (HttpContext.IsTurboFrameRequestWithPrefix("item_"))
{
    return Partial("_CartItem", Model);
}

// Get the raw frame ID
string? frameId = HttpContext.GetTurboFrameId();

How It Works

1. User clicks a link or submits a form targeting a <turbo-frame>
2. Turbo.js sends a request with the Turbo-Frame header
3. Your page handler checks for the header and returns a partial view
4. Turbo.js extracts the matching frame from the response and updates the DOM

This approach is simple, explicit, and gives you full control over what content is returned.

Documentation

Guides

• Turbo Frames Guide - Partial page updates
• Turbo Streams Guide - Real-time updates
• Authorization Guide - Securing streams
• Testing Guide - Testing strategies
• Troubleshooting - Common issues

API Reference

• ITurbo - Main service interface
• ITurboStreamBuilder - Stream builder
• TurboOptions - Configuration
• Tag Helpers - Razor tag helpers

Migration Guides

• From Blazor Server
• From HTMX

Sample Applications

The repository includes three sample applications:

Tombatron.Turbo.Sample - Turbo Frames for partial page updates and Turbo Streams for real-time notifications, including a shopping cart with add/remove operations.

Tombatron.Turbo.Chat - Real-time multi-room chat using room-based streams, typing indicators, private messaging, and the source-generated Partials class for strongly-typed partial rendering.

Tombatron.Turbo.Dashboard - Live metrics dashboard using Broadcast() from a background service to push updates to all connected clients every 2 seconds.

Run any sample:

cd samples/Tombatron.Turbo.Sample
dotnet run

Requirements

• .NET 9.0 or later
• ASP.NET Core
• Turbo.js 8.x (client-side)
• SignalR (for Turbo Streams)

Publishing / Releases

Both the NuGet and npm packages are published automatically when a version tag is pushed:

git tag v1.2.3
git push origin v1.2.3

This triggers the Release workflow which builds, tests, and publishes:

• Tombatron.Turbo to NuGet
• @tombatron/turbo-signalr to npm

The npm package can also be published independently via the manual workflow.

License

MIT License - see LICENSE for details.