Prerequisites

Before you get started, make sure that you have:

• Read and tried out the Stimulus Handbook The following pages do not attempt to describe Stimulus concepts, but instead focus on how to write Stimulus controllers using a familiar Ruby syntax.
• Ruby and bundler installed.

Installation

The process here is the same as the one described in the Stimulus handbook:

$ git clone https://github.com/ruby2js/stimulus-starter.git
$ cd stimulus-starter
$ yarn install
$ yarn start

If you are using Google Chrome, Safari, Mozilla Firefox, or Microsoft Edge, you should see a browser window with the words It works! displayed. If you are using another browser, you may need to tweak the configuration, see below.

Configuration

This starter kit uses Snowpack, which is configured using snowpack.config.js:

module.exports = {
  mount: {
    public: {url: "/", static: true, resolve: false},
    src: "/"
  },

  plugins: [
    ["@rubys/snowpack-plugin-require-context", {
      input: ['application.js']
    }],

    ["@ruby2js/snowpack-plugin", {
      eslevel: 2022,
      autoexports: "default",
      filters: ["stimulus", "esm", "functions"]
    }]
  ]
}

We mount two directories. public which contains static resources and src which contains our logic.

We are also making use of two plugins. The first is require-context which rebuilds application.js whenever files in the directory it specifies changes. You can see the generated application by visiting http://localhost:8080/application.js in your browser.

The second plugin is the one that adds Ruby2JS support to Snowpack. A description of the available configuration options can be found on the Ruby2JS site.

The option that is of most interest here is the eslevel option. It is currently set to 2022, meaning that it enables some JavaScript features which are not yet standardized and/or widely deployed. Feel free to change this value to 2021 (or lower) and restart the server by pressing control-C and then executing yarn start again.

The only downside to using a lower eslevel is that the code generated to run in the browser might be slightly more verbose and/or slightly less elegant, but rest assured that it still will work.

Technical Background

The Hotwired Stimulus Starter kit is based on Babel and Webpack. It uses Babel to convert a (slightly future) version of JavaScript to a (possibly backlevel) version of JavaScript that will be understood by your browser. This is configured via a plugin.

The Ruby2JS Stimulus Starter kit is based on Ruby2JS and Snowpack. Ruby2JS fulfils the role that Babel plays in the Hotwired Stimulus Starter in that it converts a modern Ruby syntax to a (possibly backlevel) version of Javascript that will be understood by your browser.

The generated JavaScript is functionally equivalent to the JavaScript that you would hand generate to perform the same function. This means that the generated production bundle will be just as small as if you had coded the JavaScript yourself, and will be fully compatible with other JavaScript classes you may have. In other words, you can freely mix and match Ruby and JavaScript components in the same application.

For this reason, there is no lock-in. You can start in Ruby and if you should ever decide to convert a class to JavaScript, feel free to check in the generated code as a starting point and evolve it from there.

With this starter kit, Snowpack is used instead of Webpack as it will serve up individual files unbundled, making viewing the generated source practical.

See for yourself. Compare example_controller.js with example_controller.js.rb.

Make a change. See it deployed in milliseconds.