Type of PR (feature, enhancement, bug fix, etc.)

Feature

Description

With sincere and genuine apologies for how long this has been in the oven, here is my best attempt at providing a luxe, single-command install task for SR. It builds directly on the techniques and outputs of preceding foundational efforts by both Julian and Marco.

It supports all major bundlers in their default configuration:

Rails 6.1: webpacker 5.4.3, shakapacker, vite
Rails 7: importmap, esbuild, shakapacker, vite

The installer is divided into steps which are designed to be either generic or highly specific to one of the bundlers.

The installer uses temporary files to maintain state; one of the major wins is that it means the setup process can fail, they can fix an issue, and task is smart enough to resume where they left off. It will also survive a reboot, which is something you cannot say about environment variables.

One of the things I'm most excited about is the new example the install task offers to generate. Instead of just a Reflex class and Stimulus controller, I realized that there's huge value in creating something that people can just run out of the box. This creates a controller, fully self-contained view and root. Right now, it's super minimalist, but I talk more in the Why section below about my vision for this.

I stash an MD5 hash of Gemfile so that we only need to run bundle if something changes. Likewise, I actually dynamically rebuild package.json based on added dependencies, development dependencies and removed dependencies. This allows us to run the dreaded, slow AF yarn build process 0 or 1 times, instead of 3 times since there is no way to combine these three operations on the command line.

I make efforts to create or modify most files in-place, but for files like the {entrypoint}/controllers/index.js where it's likely they made changes, it copies the existing file to .bak, generates a "perfect" new file, and then gives them a list of such replacements at the end.

rails stimulus_reflex:install # fully automatic detections, with prompts
rails stimulus_reflex:install esbuild # specify a bundler
rails stimulus_reflex:install entrypoint=app/frontend webpacker # install with webpacker 5.4.3 in app/frontend
rails stimulus_reflex:install:step action_cable yarn bundle # re-run one or more steps
rails stimulus_reflex:install:restart # wipe state and restart install

rails stimulus_reflex:install uncomment=true # uncomment any necessary includes that have been commented
rails stimulus_reflex:install spring=false # do not remove spring (equivalent to answering `n`)
rails stimulus_reflex:install example=true # create an example page and route
rails stimulus_reflex:install trace=true # debug install process with full stack trace

rails stimulus_reflex:install:step mrujs # force install mrujs
rails stimulus_reflex:install:step compression # monkey patch Action Cable to compress WS traffic with deflate

# full fat install with zero interactive prompts, suitable for scripting
rails stimulus_reflex:install esbuild entrypoint=app/javascript uncomment=true example=true

Why should this be added

First, we really need to up our installation and integration game to overcome the emotional barrier people often feel when comparing us against a built-in solution. The more we can make installing SR/CR feel like ordering a Big Mac combo, the less water "golden path" arguments hold.

Second, I am convinced that one of the most powerful things we can do to advance the adoption of this stack is to put as much energy into the onboarding experience as we can, and to that end, I want to develop the built-in example to showcase as many core concepts and differentiating features as we can on one page. I'm picturing an engaging "long scroll" that alternates between live demos with code examples, short lists of compelling features and maybe even a few testimonials, like a microsite.

The CableReady version now lives at stimulusreflex/cable_ready#233.

Checklist

• My code follows the style guidelines of this project
• Checks (StandardRB & Prettier-Standard) are passing