Getting Started Link to heading

The following steps describe how to add LiveComponent to an existing Rails application.

Install gem Link to heading

First, install the live_component Ruby gem. Typically this is done by adding it to your Gemfile:

gem "live_component", "~> 1.0"

gem "live_component", "~> 1.0"

Once the gem is listed in your Gemfile, you can run bundle install to install it.

Alternatively, you can add live_component to your bundle via bundle add:

bundle add live_component

bundle add live_component

Install JavaScript package Link to heading

Next, install the JavaScript package using your package manager of choice. Add it to your package.json file, eg:

"dependencies": {
  "@camertron/live-component": "^1.0.0"
}

"dependencies": {
  "@camertron/live-component": "^1.0.0"
}

Once the package is listed in your package.json, you can run npm install (or another similar command depending on your package manager) to install it.

Alternatively, you can add live-component to your application via npm add or similar:

npm add @camertron/live-component --save

npm add @camertron/live-component --save

Insert middleware Link to heading

One of the ways LiveComponent achieves good performance is by avoiding a significant amount of Rails overhead. It does so by inserting Rack middleware at the very beginning of the middleware stack.

In config.ru, require the LiveComponent gem and add the middleware. Your config.ru should look very similar to this:

require_relative "config/environment"
require "live_component/middleware"  # <-- add this line

use LiveComponent::Middleware  # <-- add this line
run Rails.application

Rails.application.load_server

require_relative "config/environment"
require "live_component/middleware"  # <-- add this line

use LiveComponent::Middleware  # <-- add this line
run Rails.application

Rails.application.load_server

Add JavaScript Link to heading

LiveComponent's JavaScript works best with a bundler like Vite or Webpack, and has not been tested with importmaps. LiveComponent also makes use of TypeScript decorators, which are an experimental feature not yet available in vanilla JavaScript. For that reason, all the documentation examples use TypeScript.

On the client-side, LiveComponent is really just a fancy Stimulus controller. In your application's entrypoint, eg. app/javascript/entrypoint/application.ts, start Stimulus and then start LiveComponent:

// Import with aliases to distinguish the two Application classes
import { Application as LiveComponentApplication } from "@camertron/live-component";
import { Application as StimulusApplication } from "@hotwired/stimulus";

// Add some declarations on window to make the TypeScript compiler happy
declare global {
  interface Window {
    Stimulus: StimulusApplication;
    Live: LiveComponentApplication;
  }
}

// Start both the Stimulus and LiveComponent applications
window.Stimulus = StimulusApplication.start();
window.Live = LiveComponentApplication.start(window.Stimulus);

// Import with aliases to distinguish the two Application classes
import { Application as LiveComponentApplication } from "@camertron/live-component";
import { Application as StimulusApplication } from "@hotwired/stimulus";

// Add some declarations on window to make the TypeScript compiler happy
declare global {
  interface Window {
    Stimulus: StimulusApplication;
    Live: LiveComponentApplication;
  }
}

// Start both the Stimulus and LiveComponent applications
window.Stimulus = StimulusApplication.start();
window.Live = LiveComponentApplication.start(window.Stimulus);

LiveComponent should now be ready to use 🎉🎉🎉