TurboLive

TurboLive is a Ruby gem that enables the creation of async, progressively enhanced, live components for Ruby applications. It works seamlessly over both WebSockets and HTTPS, providing real-time interactivity with graceful degradation.

• Installation
• Setup
• Usage
  • Creating a Component
  • Model State
  • View
  • Update
• Events
  • Manual Events
  • Timed Events
• Examples
• Performance Considerations
• Testing
• Troubleshooting
• Contributing
• Changelog
• License

Add it to your project with:

bundle add 'turbo_live'

Or install it yourself using:

gem install turbo_live

TurboLive ships a JavaScript component that comes as an npm package. You can pin it with importmaps or install it as an npm package depending on your asset pipeline:

For importmaps:

bin/importmap pin @radioactive-labs/turbo-live

For yarn:

yarn add @radioactive-labs/turbo-live

Or YAR:

npm install @radioactive-labs/turbo-live

In your rails routes, mount the engine:

Rails.application.routes.draw do
  # Define your application routes per the DSL in https://guides.rubyonrails.org/routing.html

+  mount TurboLive::Engine => "/turbo_live"

  # Defines the root path route ("/")
  root "index#index"
end

TurboLive uses a Stimulus controller to manage interactions. In your app/javascript/controllers/index.js:

import { application } from "controllers/application"
import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"

eagerLoadControllersFrom("controllers", application)

+import * as turboLive from "@radioactive-labs/turbo-live"
+turboLive.registerControllers(application)

TurboLive supports WebSockets using ActionCable with automatic failover to HTTPS. If you have ActionCable set up and would like to benefit from better performance, you can set up the integration.

In app/javascript/channels/index.js:

+import consumer from "./consumer"
+import * as turboLive from "@radioactive-labs/turbo-live"
+
+turboLive.registerChannels(consumer)

Then in your app/javascript/application.js:

import "@hotwired/turbo-rails"
import "controllers"
+import "channels"

A TurboLive component is a self-contained, interactive unit of a web application that can update in real-time without full page reloads. Components follow The Elm Architecture pattern.

To create a TurboLive component, inherit from TurboLive::Component:

class MyComponent < TurboLive::Component
  # Component logic goes here
end

Define state variables using the state method:

class MyComponent < TurboLive::Component
  state :count, Integer do |value|
    value || 0
  end
end

Note: State variables can only be primitive objects and basic collections.

Define the component's HTML structure in the view method:

def view
  div do
    button(**on(click: :increment)) { "+" }
    span { count }
    button(**on(click: :decrement)) { "-" }
  end
end

Components are phlex views, allowing you to write HTML in Ruby.

Handle events in the update method:

def update(input)
  case input
  in :increment
    self.count += 1
  in :decrement
    self.count -= 1
  end
end

Events are transmitted to the server using the currently active transport (HTTP or WebSockets).

Use the on method to set up manually triggered events:

button(**on(click: :decrement)) { "-" }

You can also emit compound events that carry extra data:

button(**on(click: [:change_value, 1])) { "+" }

Certain events carry extra data as well, such as input and change events.

input(value:, input_value, **on(input: :input_changed))

def update(input)
  case input
  in [:input_changed, value]
    self.input_value = value
  end
end

> Note: Currently, only `:click`, `:input` and `:change` events are supported.

### Timed Events

Use the `every` method to set up recurring events:

```ruby
def view
  div do
    h1 { countdown }
    every(1000, :tick) if countdown > 0
  end
end

See the /examples folder in for detailed component examples including Counter, Countdown, Showcase and Tic-Tac-Toe components.

• Use fine-grained components to minimize the amount of data transferred and rendered.
• Implement debouncing for frequently triggered events.
• Consider using background jobs for heavy computations to keep the UI responsive.

TurboLive components can be tested using standard Rails testing tools. Here's a basic example:

require "test_helper"

class CounterComponentTest < ActiveSupport::TestCase
  test "increments count" do
    component = CounterComponent.new
    assert_equal 0, component.count
    component.update(:increment)
    assert_equal 1, component.count
  end
end

Common issues and their solutions:

1. Component not updating: Ensure that your update method is correctly handling the event and modifying the state.
2. WebSocket connection failing: Check your ActionCable configuration and ensure that your server supports WebSocket connections.
3. JavaScript errors: Make sure you've correctly set up the TurboLive JavaScript integration in your application.
4. My timed events won't go away: Due to the use of morphing, there might be instances where your some meta attributes are not removed.

For more issues, please check our FAQ or open an issue on GitHub.

We welcome contributions to TurboLive! Please see our Contributing Guidelines for more information on how to get started.

See the CHANGELOG.md file for details on each release.

The gem is available as open source under the terms of the MIT License.