Welcome to TurboBoost Streams 👋

TurboBoost Streams extends Turbo Streams to give you full control of the browser's Document Object Model (DOM).

1turbo_stream.invoke "console.log", args: ["Hello World!"]

That's right! You can invoke any DOM method on the client with Turbo Streams.

Table of Contents

• Why boosted Streams?
• Sponsors
• Community
• Dependencies
• Installation
• Setup
• Usage
  • Method Chaining
  • Event Dispatch
  • Morph
  • Morph Method
  • Syntax Styles
  • Extending Behavior
  • Implementation Details
  • Broadcasting
    • Background Job Queues
• FAQ
• A Word of Warning
• Developing
  • Notable Files
• Deploying
  • Notable Files
  • How to Deploy
• Releasing
• About TurboBoost
• License

Why boosted Streams?

Turbo Streams intentionally restrict official actions to CRUD-related activity. These official actions work well for a considerable number of use cases. We recommend that you push Turbo Streams as far as possible before reaching for boosted streams.

If you find that CRUD isn't enough, boosted streams are there to handle pretty much everything else.

Sponsors

Proudly sponsored by

Community

Come join the party with over 2200+ like-minded friendly Rails/Hotwire enthusiasts on our Discord server.

Dependencies

• rails >= 6.1
• turbo-rails >= 1.1
• @hotwired/turbo-rails >= 7.2

Installation

Be sure to install the same version for each library.

1bundle add "turbo_boost-streams --version VERSION"
2npm install "@turbo-boost/streams@VERSION"

Setup

Import and initialize Turbo Boost Streams in your application.

1# Gemfile
2gem "turbo-rails", ">= 1.1", "< 2"
3+gem "turbo_boost-streams", "~> VERSION"

1# package.json
2"dependencies": {
3  "@hotwired/turbo-rails": ">=7.2",
4+  "@turbo-boost/streams": "^VERSION"

1# app/javascript/application.js
2import '@hotwired/turbo-rails'
3+import '@turbo-boost/streams'

Usage

Manipulate the DOM from anywhere you use official Turbo Streams. The possibilities are endless. Learn more about the DOM at MDN.

1turbo_stream.invoke "console.log", args: ["Hello World!"]

Method Chaining

You can use dot notation or selectors and even combine them!

1turbo_stream
2  .invoke("document.body.insertAdjacentHTML", args: ["afterbegin", "<h1>Hello World!</h1>"]) # dot notation
3  .invoke("setAttribute", args: ["data-turbo-ready", true], selector: ".button") # selector
4  .invoke("classList.add", args: ["turbo-ready"], selector: "a") # dot notation + selector

Event Dispatch

It's possible to fire events on window, document, and element(s).

1turbo_stream
2  .invoke(:dispatch_event, args: ["turbo-ready:demo"]) # fires on window
3  .invoke("document.dispatchEvent", args: ["turbo-ready:demo"]) # fires on document
4  .invoke(:dispatch_event, args: ["turbo-ready:demo"], selector: "#my-element") # fires on matching element(s)
5  .invoke(:dispatch_event, args: ["turbo-ready:demo", {bubbles: true, detail: {...}}]) # set event options

Morph

You can morph elements with the morph method.

1turbo_stream.invoke(:morph, args: [render("path/to/partial")], selector: "#my-element")

[!NOTE] TurboBoost Streams uses Idiomorph for morphing.

The following options are used to morph elements.

1{
2  morphStyle: 'outerHTML',
3  ignoreActiveValue: true,
4  head: { style: 'merge' },
5  callbacks: { beforeNodeMorphed: (oldNode, _) => ... }
6}

[!TIP] The callbacks honor the data-turbo-permanent attribute and is aware of the Trix editor.

Morph Method

The morph method is also exported to the TurboBoost.Streams global and is available for client side morphing.

1TurboBoost.Streams.morph.method // → function(targetNode, htmlString, options = {})

You can also override the morph method if desired.

1TurboBoost.Streams.morph.method = (targetNode, htmlString, options = {}) => {
2  // your custom implementation
3}

It also support adding a delay before morphing is performed.

1TurboBoost.Streams.morph.delay = 50 // → 50ms

[!TIP] Complex test suites may require a delay to ensure the DOM is ready before morphing.

Syntax Styles

You can use snake_case when invoking DOM functionality. It will implicitly convert to camelCase.

1turbo_stream.invoke :event,
2  args: ["turbo-ready:demo", {detail: {converts_to_camel_case: true}}]

Need to opt-out? No problem... just disable it.

1turbo_stream.invoke :contrived_demo, camelize: false

Extending Behavior

If you add new capabilities to the browser, you can control them from the server.

1// JavaScript on the client
2import morphdom from 'morphdom'
3
4window.MyNamespace = { coolStuff: (arg) => { ... } }

1# Ruby on the server
2turbo_stream.invoke "MyNamespace.coolStuff", args: ["Hello World!"]

Implementation Details

There's basically one method to learn... invoke

1# Ruby
2turbo_stream
3  .invoke(method, args: [], selector: nil, camelize: true, id: nil)
4#         |       |         |              |               |
5#         |       |         |              |               |- Identifies this invocation (optional)
6#         |       |         |              |
7#         |       |         |              |- Should we camelize the JavaScript stuff? (optional)
8#         |       |         |                 (allows us to write snake_case in Ruby)
9#         |       |         |
10#         |       |         |- A CSS selector for the element(s) to target (optional)
11#         |       |
12#         |       |- The arguments to pass to the JavaScript method (optional)
13#         |
14#         |- The JavaScript method to invoke (can use dot notation)

📘 NOTE: The method will be invoked on all matching elements if a selector is present.

The following Ruby code,

1turbo_stream.invoke "console.log", args: ["Hello World!"], id: "123ABC"

emits this HTML markup.

1<turbo-stream action="invoke" target="DOM">
2  <template>{"id":"123ABC","receiver":"console","method":"log","args":["Hello World!"]}</template>
3</turbo-stream>

When this element enters the DOM, Turbo Streams automatically executes invoke on the client with the template's JSON payload and then removes the element from the DOM.

Broadcasting

You can also broadcast DOM invocations to subscribed users.

1. First, setup the stream subscription.

   1<!-- app/views/posts/show.html.erb -->
   2<%= turbo_stream_from @post %>
   3<!--                  |
   4                      |- *streamables - model(s), string(s), etc...
   5-->

2. Then, broadcast to the subscription.

   1# app/models/post.rb
   2class Post < ApplicationRecord
   3  after_save do
   4    # emit a message in the browser console for anyone subscribed to this post
   5    broadcast_invoke "console.log", args: ["Post was saved! #{to_gid}"]
   6
   7    # broadcast with a background job
   8    broadcast_invoke_later "console.log", args: ["Post was saved! #{to_gid}"]
   9  end
   10end

   1# app/controllers/posts_controller.rb
   2class PostsController < ApplicationController
   3  def create
   4    @post = Post.find params[:id]
   5
   6    if @post.update post_params
   7      # emit a message in the browser console for anyone subscribed to this post
   8      @post.broadcast_invoke "console.log", args: ["Post was saved! #{@post.to_gid}"]
   9
   10      # broadcast with a background job
   11      @post.broadcast_invoke_later "console.log", args: ["Post was saved! #{@postto_gid}"]
   12
   13      # you can also broadcast directly from the channel
   14      Turbo::StreamsChannel.broadcast_invoke_to @post, "console.log",
   15        args: ["Post was saved! #{@post.to_gid}"]
   16
   17      # broadcast with a background job
   18      Turbo::StreamsChannel.broadcast_invoke_later_to @post, "console.log",
   19        args: ["Post was saved! #{@post.to_gid}"]
   20    end
   21  end
   22end

📘 NOTE: Method Chaining is not currently supported when broadcasting.

Background Job Queues

You may want to change the queue name for Turbo Stream background jobs in order to isolate, prioritize, and scale the workers independently.

1# config/initializers/turbo_streams.rb
2Turbo::Streams::BroadcastJob.queue_name = :turbo_streams
3TurboBoost::Streams::BroadcastInvokeJob.queue_name = :turbo_streams

FAQ

• Isn't this just RJS?

  No. But, perhaps it could be considered RJS's "modern" spiritual successor. 🤷‍♂️ Though it embraces JavaScript instead of trying to avoid it.

• Does it use eval?

  No. The invoke stream can only execute existing functions on the client. It's not a carte blanche invitation to emit free-form JavaScript to be evaluated on the client.

A Word of Warning

TurboBoost Streams is a foundational tool designed to help you build modern, maintainable, and scalable reactive web apps with Hotwire. It allows you to break free from the strict CRUD/REST conventions that Rails and Hotwire wisely encourage. You should consider boosted streams a substrate for building additional libraries and abstractions.

Please don't use TurboBoost Streams to manually orchestrate micro DOM updates (from the server). Such techniques are what gave rise to Full Stack Frontend and sent the industry on a decade-long journey of complexity and frustration.

Developing

This project supports a fully Dockerized development experience.

1. Simply run the following commands to get started.

   1git clone -o github https://github.com/hopsoft/turbo_boost-streams.git
   2cd turbo_boost-streams

   1docker compose up -d # start the environment (will take a few minutes on 1st run)
   2docker exec -it turbo_boost-streams-web rake # run the test suite
   3open http://localhost:3000 # open the `test/dummy` app in a browser

   And, if you're using the containers gem (WIP).

   1containers up # start the environment (will take a few minutes on 1st run)
   2containers rake # run the test suite
   3open http://localhost:3000 # open the `test/dummy` app in a browser

2. Edit files using your preferred tools on the host machine.

3. That's it!

Notable Files

• Dockerfile
• docker-compose.yml
• bin/docker/run/local

Deploying

This project supports Dockerized deployment via the same configuration used for development, and... it actually runs the test/dummy application in "production". 🤯

The test/dummy app serves the following purposes.

• Test app for the Rails engine
• Documentation and marketing site with interactive demos

You can see it in action here. How's that for innovative simplicity?

Notable Files

• Dockerfile
• fly.toml
• bin/docker/run/remote

How to Deploy

1fly deploy

Releasing

[!TIP] Run these commands on the host machine (i.e. not inside the dev container)

1. Run npm update and bundle update to pick up the latest dependencies
2. Update the version number consistently in the following files:
   • lib/turbo_boost/streams/version.rb - pre-release versions should use .preN
   • app/javascript/version.js - pre-release versions use -preN
   • package.json - pre-release versions use -preN
3. Run bin/standardize
4. Run rake build
5. Run npm run build
6. Commit and push any changes to GitHub
7. Run rake release
8. Run npm publish --access public
9. Create a new release on GitHub (here) and generate the changelog for the stable release for it

About TurboBoost

TurboBoost is a suite of libraries that enhance Rails, Hotwire, and Turbo... making them even more powerful and boosting your productivity. Be sure to check out all of the various libraries.

• Streams
• Commands
• Elements
• Devtools
• Coming soon...

License

These libraries are available as open source under the terms of the MIT License.