turbo_live

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.

Table of Contents

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

Installation

Add it to your project with:

bundle add 'turbo_live'

Or install it yourself using:

gem install turbo_live

JavaScript

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

Setup

Rails Routes

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

Stimulus Controller

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)

ActionCable (Optional)

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"

Usage

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.

Creating a Component

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

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

Model State

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.

View

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.

Update

Handle events in the update method:

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

Events

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

Manual Events

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

Examples

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

Performance Considerations

• 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.

Testing

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

Troubleshooting

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.

Contributing

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

Changelog

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

License

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