How to prepare your app to use StimulusReflex

Command-Line Install

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

# For new projects
rails new myproject --webpack=stimulus
cd myproject
# For existing projects
bundle exec rails webpacker:install:stimulus
# For both project types
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, including enabling caching in your development environment.

And that's it! You can start using StimulusReflex in your application.

Starting with v2.2.2 of StimulusReflex, support for the Rails default session storage mechanism cookie_store has been temporarily dropped. The stimulus_reflex:install script will now set your session storage to be :cache_store in your development environment if no value has been set.

Manual Configuration

Some developers will need more control than a one-size-fits-all install task, so we're going to step through what's actually required to get up and running with StimulusReflex in your Rails 6+ project.

First, the easy stuff: let's make sure we have Stimulus installed as part of our project's Webpack configuration. We'll also install the StimulusReflex gem and client library before enabling caching in your development environment.

bundle exec rails webpacker:install:stimulus
bundle add stimulus_reflex
yarn add stimulus_reflex
rails dev:cache

We need to modify our Stimulus configuration to import and initialize StimulusReflex, which will attempt to locate the existing ActionCable consumer. A new websocket connection is created if the consumer isn't found.

import { Application } from 'stimulus'
import { definitionsFromContext } from 'stimulus/webpack-helpers'
import StimulusReflex from 'stimulus_reflex'
import consumer from '../channels/consumer'
const application = Application.start()
const context = require.context('controllers', true, /_controller\.js$/)
StimulusReflex.initialize(application, { consumer })

Cookie-based session management is not currently supported by StimulusReflex. We will set our session management to be managed by the cache store, which in Rails defaults to the memory store.

Rails.application.configure do
config.session_store :cache_store
# ....

Configure ActionCable to use the Redis adapter in development mode. If you don't have Redis, you can learn more on the Redis site.

adapter: redis
url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>
channel_prefix: your_application_development

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

<%= csrf_meta_tags %>
<%= csp_meta_tag %>
<%= action_cable_meta_tag %>

Running "Edge"

If you are interested in running the latest version of StimulusReflex, you can point to the master branch on Github:

"dependencies": {
"stimulus_reflex": "hopsoft/stimulus_reflex#master"
gem 'stimulus_reflex', github: 'hopsoft/stimulus_reflex'

Don't forget to run bundle install && yarn install --check-files after you change your configuration.

As always, it is really important to always make sure that your Ruby and Javascript package versions are the same!


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.

Session Storage

We are strong believers in the Rails Doctrine and work very hard to prioritize convention over configuration. Unfortunately, there are some inherent limitations to the way cookies are communicated via websockets that make it difficult to use cookies for session storage in production. We've had to make the decision to temporarily drop support for the Rails default cookie-based session store.

This puts us in the awkward position of forcing an infrastructure change for some users that has nuanced implications.

We decided to default to using the :cache_store for config.session_store (and enabling caching) in the development environment if no other option has been declared. If you set a different session store in an initializer, please make sure that we're not clobbering your preferred store with our good intentions. The Rails default cache store is :memory_store which will get the job done in development but is not suitable or appropriate for production.

You can learn more about session storage on the Deployment page.


StimulusReflex supports both client and server logging of Reflexes.

ViewComponent Integration

There is no special process required for using view_component with StimulusReflex. If ViewComponent is setup and running properly, you're already able to use them in your Reflex-enabled views.

Many StimulusReflex + ViewComponent developers are enjoying using the view_component_reflex gem, which automatically persists component state to your session between Reflexes.

Rails 5.2+ Support

To use Rails 5.2 with StimulusReflex, you'll need the latest Action Cable package from npm: @rails/actioncable

  1. Replace actioncable with @rails/actioncable in package.json

    • yarn remove actioncable

    • yarn add @rails/actioncable

  2. Replace any instance of import Actioncable from "actioncable" with import { createConsumer } from "@rails/actioncable"

    • This imports the createConsumer function directly

    • Previously, you might call createConsumer() on the Actioncable import: Actioncable.createConsumer()

    • Now, you can reference createConsumer() directly

There's nothing about StimulusReflex 3+ that shouldn't work fine in a Rails 5.2 app if you're willing to do a bit of manual package dependency management.