Installation
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.