turbo.cr

A 1:1 Crystal port of turbo-rails 2.0.20 (Hotwire Turbo Streams) with the namespace Turbo, built on top of action_view.cr, action_pack.cr, action_cable.cr, active_record.cr and active_job.cr. Covers the stream tag builder (turbo_stream.append/prepend/...), cable broadcasting (broadcast_*_to, declarative broadcasts/broadcasts_to on models), _later jobs over ActiveJob, view helpers (turbo_stream_from, turbo_frame_tag) and the text/vnd.turbo-stream.html HTTP format. Client side is the official vendored @hotwired/turbo 8.0.13 UMD plus a ~60-line cable connector instead of the npm bundle. Suite: 60/60 oracle cases recorded from the real gem + an E2E smoke of the demo app.

⚠️ EXPERIMENTAL FRAMEWORK, DO NOT USE IN PRODUCTION YET.

Installation

dependencies:
  turbo_cr:
    github: OrelSokolov/turbo.cr

shards install

Depends on active_support.cr, action_view.cr, action_pack.cr, action_cable.cr, active_record.cr and active_job.cr.

Usage

# In a view or turbo_stream template:
turbo_stream.append "entries", "<div>hi</div>"
turbo_stream.remove "clearance_5"
turbo_stream.update "entries", partial: "entries/entry", locals: {"entry" => entry}
turbo_stream.refresh

turbo_frame_tag "cart", src: "/cart", loading: "lazy" { }
turbo_stream_from "room", "entries"

# From a model or controller:
Turbo::StreamsChannel.broadcast_prepend_to ["entries"],
  target: "entries", content: "<div>new</div>"

class Message < ActiveRecord::Base
  include Turbo::Broadcastable
  broadcasts_to :board, inserts_by: :prepend, target: "board_messages"
end

Feature comparison vs turbo-rails 2.0.20

Streams tag builder & view helpers

Broadcasting

Jobs, channel & HTTP format

Deviations & Crystal-specific notes

• kwargs → named args: turbo_stream.append target, "text" instead of **options.
• Renderer seam instead of ApplicationController.render: compiled languages can't render from a string at runtime — the app registers Turbo.partial_renderer / Turbo.template_renderer procs over compile-time-compiled partials/templates. See spec/oracle_spec.cr (TurboView) and demo (src/turbo_renderers.cr) for boilerplate.
• broadcasts macro: pluralize is a runtime inflector, unavailable in macro-land — the stream name is computed at runtime.
• Block overloads are typed (&block : Proc(String)) because untyped blocks passed through as Proc return nil; locals are normalized via Turbo.cast_locals (generics invariance); ActiveJob argument hashes are strictly Hash(String | Symbol, ArgValue).
• Declarative macros live in the Broadcastable module body (plain methods in ClassMethods via macro included) because extend inside macro included doesn't hoist macros.

Testing

make spec    # = CRAILS_VIEWS=spec/fixtures/views crystal spec

Requires a local PostgreSQL (default postgres://root@/crails_turbo_spec?host=/var/run/postgresql, override with TURBO_SPEC_URL); Redis is not needed (in-process Test subscription adapter). Oracle: 60 cases recorded from the real turbo-rails 2.0.20 + rails 8.1.4 (DB crails_turbo_oracle, TZ=UTC) in oracle/cases.rb → oracle/expected.yml; the Crystal mirror spec/oracle_spec.cr replays them 1:1 without edits (expected raise cases included). E2E smoke spec/e2e_smoke.cr additionally needs the demo app running: demo/bin/app serve -p 3001.