Setup

How to prepare your app to use StimulusReflex

StimulusReflex relies on Stimulus, an excellent library from the creators of Rails. You can easily install StimulusReflex to new and existing Rails projects.

rails new myproject --webpack=stimulus
cd myproject
bundle add stimulus_reflex
bundle exec rails stimulus_reflex:install

The terminal commands above will ensure that both Stimulus and StimulusReflex are installed. It creates common files and an example to get you started. It also handles some of the configuration outlined below.

Configuration

Update your Stimulus configuration and make sure that stimulus_reflex is in your Gemfile:

app/javascript/controllers/index.js
Gemfile
app/javascript/controllers/index.js
import { Application } from 'stimulus'
import { definitionsFromContext } from 'stimulus/webpack-helpers'
import StimulusReflex from 'stimulus_reflex'
const application = Application.start()
const context = require.context('controllers', true, /_controller\.js$/)
application.load(definitionsFromContext(context))
StimulusReflex.initialize(application)
Gemfile
gem "stimulus_reflex"

You should add the action_cable_meta_taghelper to your application template so that ActionCable can access important configuration settings:

app/views/layouts/application.html.erb
<head>
<%= csrf_meta_tags %>
<%= csp_meta_tag %>
<%= action_cable_meta_tag %>
</head>

Authentication

If you're just experimenting with StimulusReflex or trying to bootstrap a proof-of-concept application on your local workstation, you can actually skip this section until you're planning to deploy.

Out of the box, ActionCable doesn't give StimulusReflex the ability to distinguish between multiple concurrent users looking at the same page.

If you deploy to a host with more than one person accessing your app, you'll find that you're sharing a session and seeing other people's updates. That isn't what most developers have in mind!

When the time comes, it's easy to configure your application to support authenticating users by their Rails session or current_user scope. Just check out the Authentication page and choose your own adventure.

Logging

In the default debug log level, ActionCable emits particularly verbose log messages. You can optionally discard everything but exceptions by switching to the warn log level, as is common in development environments:

config/environments/development.rb
# :debug, :info, :warn, :error, :fatal, :unknown
config.log_level = :warn

Alternatively, disabling just ActionCable logs may improve performance.

config/initializers/action_cable.rb
ActionCable.server.config.logger = Logger.new(nil)

Troubleshooting

If something goes wrong, it's often because of the spring gem. You can test this by temporarily setting the DISABLE_SPRING=1 environment variable and restarting your server.

To remove spring forever, here is the process we recommend:

  1. pkill -f spring

  2. Edit your Gemfile and comment out spring and spring-watcher-listen

  3. bin/spring binstub –remove –all