Ruby2JS

The Ruby2JS Story: A Decade of Transpilation

2025-12-14T00:00:00-05:00

Ruby2JS began in October 2013, forked from Marcos Castoria’s original maca/Ruby2JS project. The timing was notable: JavaScript was still in its ES5 era. Classes required prototype chain manipulation. Modules didn’t exist—you used AMD, CommonJS, or globals. Destructuring? Arrow functions? Forget it.

The appeal of transpiling Ruby to JavaScript was straightforward: write elegant Ruby syntax and generate the verbose JavaScript that browsers understood.

The Early Years (2013-2019)

Development was intense in the beginning—159 commits in just the final two months of 2013. The codebase grew steadily:

Year	Commits	Notes
2013	159	Project launch
2014	96	Steady growth
2015	161	React filter added
2016	11	Activity slowdown
2017	116	Recovery
2018	177	ES2015 support finally added
2019	57	Tapering off

The irony wasn’t lost on anyone: ES2015 (ES6) shipped in June 2015, but Ruby2JS didn’t add ES2015 class support until December 2017—over two years later. By then, JavaScript had native classes, modules, arrow functions, template literals, destructuring, and spread operators. The gap that Ruby2JS originally filled was closing.

Jared White Enters (October 2020)

In October 2020, Jared White arrived and reinvigorated the project. His first commits landed on October 6, 2020, focused on tagged template literals and camelCase filter improvements.

What followed was remarkable. In just over a year, Jared:

Built the ruby2js.com website using Bridgetown (launched December 2020)
Drove version 4.0.0 (February 2021) with major modernizations
Added the Stimulus filter for Hotwire integration
Created LitElement support
Expanded the preset system for easier configuration
Released version 5.0.0 (May 2022)

The numbers tell the story. The project hit its peak activity with 451 commits in 2021—more than any previous year. Jared contributed 199 commits total, second only to my 1,615.

Jared brought something the project desperately needed: energy, vision, and a focus on modern web development patterns. The Bridgetown documentation site he built made Ruby2JS accessible to a whole new generation of developers.

The Quiet Period (2022-2024)

After version 5.0.0, activity gradually slowed:

Year	Commits
2022	65
2023	21
2024	7

By May 2024, version 5.1.2 shipped—the last release before a long pause. Opal remained stuck at version 1.1.1 due to a compilation issue that was never fully resolved. Bridgetown sat at 1.3.4. The live demos on ruby2js.com stopped working.

On January 23, 2025, Jared formally announced his departure, acknowledging that “there are a number of PRs and issues stacking up” but explaining that his time was consumed by other open source projects, particularly Bridgetown itself. He graciously noted that he hadn’t created the project and hadn’t written most of the codebase—leaving the door open for renewed stewardship.

Coming Home (November 2025)

My return was prompted by a practical need: offline functionality for a Rails application. I found the project with 21 open issues and 7 pending pull requests. The demos were broken. Dependencies were years out of date.

Since November 27, 2025, there have been over 360 commits, 30 issues closed, and 44 pull requests merged.

Infrastructure modernization:

Opal upgraded from 1.1.1 to 1.8
Bridgetown upgraded from 1.3.4 to 2.0.5
Pre-ES2020 support retired (ES2015-ES2019 removed)
Prism parser support for Ruby 3.4+

The self-hosting breakthrough:

Ruby2JS now transpiles itself to JavaScript
A unified 200KB ruby2js.mjs bundle (no Ruby required)
245 tests passing against the JavaScript implementation
Enables true dual-target development—same Ruby source running on server and browser

New framework filters:

ERB and HAML template support
Turbo for custom Turbo Stream actions
Alpine.js component registration
ActionCable WebSocket DSL
Jest for RSpec-style testing syntax
Stimulus enhanced with outlets support (3.x)

Enhanced Ruby patterns:

Type introspection (is_a?, instance_of?, respond_to?)
Class introspection (obj.class, obj.class.name, superclass)
Module mixins (include, extend)

New documentation:

Complete User’s Guide for dual-target development
Patterns, pragmas, and anti-patterns documentation
Live demos throughout

The self-hosting work was particularly significant—proving that Ruby2JS can handle substantial, real-world Ruby code by successfully converting its own 60+ converter handlers and serializer to JavaScript.

The Numbers

After 11 years:

1,901 total commits
19 releases (v3.6.0 through v5.1.2, with an upcoming 6.0 beta)
~60 AST node handlers
~23 filters (functions, esm, camelCase, react, stimulus, and more)

Thank You, Jared

Jared White kept Ruby2JS alive and relevant during a critical period. His documentation work, his filters, his energy—they transformed a useful but aging tool into something modern developers could actually adopt. The project is better for his stewardship, and I’m grateful he held the torch when I couldn’t.

Open source thrives on these handoffs. Sometimes you carry the load, sometimes you pass it on, and sometimes—years later—you pick it back up again.

Ruby2JS 5.1, esbuild, and a Peek at the Future

2023-02-20T00:00:00-05:00

At long last, Ruby2JS 5.1 is here! It comes packed with several very welcome features:

A brand-new Ruby-based configuration DSL
A “preset” option for sane defaults
Magic comment support for sharing portable Ruby2JS code (based on the preset)

In addition, the esbuild plugin has reached 1.0 status and has been re-architected to use the Ruby version of the compiler rather than the Node (aka Opal) version. Why? Performance and modern language compatibility.

Let’s dig in a bit on all these new features! And keep reading as well for an update on the status of Ruby2JS and its open source governance.

Ruby-based Configuration

Ruby2JS, despite being a language transpiler usually needing some degree of configuration, never had a canonical format for project-based configuration. Until today!

You can add config/ruby2js.rb to your project and both the Ruby API and the CLI tool will automatically detect its presence and use it for configuration. In addition, you can specify the location of a configuration file manually if you prefer to use a different filename or folder.

The configuration format is very simple and easy to work with, just like other configuration formats such as Puma. You can read all about it in the documentation here. But that’s not all!

A Preset Configuration for Sane Defaults

We believe most Ruby2JS code would benefit greatly from transpiling to a modern ECMAScript version (namely ES2021), using a few common filters such as Functions, ESM, and Return, using identity-based comparison operators (aka == becomes ===), and automatically underscoring instance variables (@x becomes this._x).

So that’s exactly what we built. By simply adding preset to a configuration file or passing preset: true or --preset to the Ruby API or CLI respectively, you can gain all the benefits of these common options. In addition, by writing your code to use the preset, you can ensure wider compatibility between projects and between tutorials/code samples and production workflows.

Even more to that point, we’ve introduced the idea of a “magic comment”. By adding # ruby2js: preset to the top of a .js.rb file, you instruct Ruby2JS to use the preset configuration for that file. You can even add additional filters right in the magic comment, change the ES level, or disable a filter that comes with the preset. Read the documentation here.

We believe all of these features now mean that Ruby2JS code is easier to teach and easier to share. We took your feedback about these issues in the past to heart and are trying to make improvements for better DX.

esbuild is faster using Ruby?!

esbuild is a modern, fast, and easily-configured frontend bundling tool, and we want to support it as a “first-party” citizen in the Ruby2JS ecosystem.

esbuild is fast because its core code is written in Go, not JavaScript. Along similar lines, we discovered something extraordinary when testing the beta of the esbuild bundling package. When we tried spawning a process to transpile a file using the Ruby version of Ruby2JS, rather than the Opal/Node-powered JavaScript version, we discovered that it was actually faster! And not just a little bit faster…almost 2x faster!

Transpiling using the Ruby version also has the added benefit that the syntax of the code you write on the frontend matches the version of Ruby your project uses overall. Before, you could be using Ruby 3.2 in your overall stack but the “version of Ruby” (in fact the version of Opal) might be older. In fact, there’s actually an outstanding issue that the version of Opal used to generate the JavaScript version of Ruby2JS is locked to an older version of Opal due to bugs introduced when upgrading. More on that below…

So, all in all, it makes sense to standardize around Ruby, even when using esbuild. After all, I would be shocked if anyone had an interest in writing Ruby2JS frontend code and using esbuild as a bundling tool who didn’t actually have Ruby installed for use in a Ruby-based web project. So why rely on Opal/Node if we don’t have to?

The Future of Ruby2JS

Which brings us to a broader topic: the future of this project.

Sam Ruby, a well-known figure in the Ruby community and the brains behind Ruby2JS for many years, stepped down as an active maintainer in 2021. This effectively left me as the sole maintainer of Ruby2JS—and not only the sole maintainer, but by and large the only active contributor to Ruby2JS.

I had started contributing to the project in 2020, and through much trial-and-error and helpful mentorship from Sam, I eventually learned my way around the codebase enough to help usher in a few improvements to the feature set as well as set up this Bridgetown documentation site. It was an amazing experience, and I’d like to thank Sam publicly for his trust in (and patience with!) me.

Here’s the deal: I love this project and sincerely hope to continue to see it fill an important role in the niche of “Ruby frontend web developers” as I like to consider myself to be.

But the fact of the matter is I have my hands very full with the Bridgetown project, and my ability to devote much attention to Ruby2JS is limited. In addition, what attention I can devote to Ruby2JS is mostly relegated to the use cases for which Ruby2JS is personally useful to me. I’m not saying that’s ideal. It just is what it is.

So because I primarily use Ruby2JS for writing web components (usually using Lit) and bundling using esbuild, that is the principal scope I intend to maintain going forward. I would also argue that it’s a very ergonomic and obvious way to make the most of Ruby2JS as a web developer building projects (as I do) with Rails or Bridgetown.

Thus I have decided to deprecate quite a number of features (“filters” and other integration points) which will be removed officially by the time Ruby2JS 6.0 is released. I don’t have any immediate release date for that, but for the sake of discussion let’s assume it will happen towards the end of this year.

The list of deprecated features is as follows:

jQuery filter
JSX filter
matchAll filter (only necessary for ES < 2020)
minitest-jasmine filter
Preact filter
React filter
Require filter
Underscore filter
Vue filter
CGI server integration
ExecJS integration
Haml integration
Rails integration (outside of the new “jsbundling” esbuild pipeline)
Sinatra integration (as a view template type)
Sprockets integration
“use strict” option (all modern ESM code is considered strict anyway)
Webpack loader

In addition, I am actively looking for a maintainer to own the Rollup and Vite plugins for transpiling Ruby2JS code via those bundlers. I don’t myself use Rollup/Vite, but I understand they’re quite popular as an alternative to using esbuild directly. They still need to be upgraded to use Ruby rather than Node for the transpilation (like esbuild).

If any of these stand out to you as having a serious impact on current production workflows, let’s talk about possible strategies—either migrations to a better solution, or extracting features out to their own repo. For example, I simply have no interest in maintaining a React filter. I don’t recommend people adopt React in new projects as a general rule, and if they do, then I recommend they use the Next.js framework because it just makes React much, much better. React + Ruby2JS is not a solution I can, in all good conscience, promote.

However, if someone really needs a React filter long into the future for their projects, I’d be happy to help extract this functionality out to a separate gem with fresh open source governance. Again, that holds true for any of the deprecated features listed above.

The alternative to this approach, and one I strongly considered, would be for me to step down myself as a maintainer of Ruby2JS and seek someone else in the community to come onboard instead. I decided against this move for several reasons:

I still really enjoy writing Ruby2JS code and singing the praises of the project.
This is a pretty gnarly codebase to wrap your head around, and I had the benefit of being mentored by Sam Ruby himself. For someone to come in fresh and begin to make sizable contributions, that’s a tall order—especially with the variety of JS packages now in the project as well. There’s also a fair bit of technical debt that has no clear upgrade path at present. For example:
We’re locked into an old version of Opal for compiling the JavaScript version of the Ruby2JS compiler. Over time, this will result in the Node version of Ruby2JS falling farther and farther behind relative to its native Ruby counterpart. It may mean that, at some future date, we sunset this other than for trivial use (such as the online interactive demos)—or we figure out why the transpiler is broken on newer version of Opal which will take a considerable amount of time (I’ve failed after two separate attempts).
And as mentioned above, nobody else has been contributing with any frequency.

So ultimately I gladly intend on continuing to act as lead maintainer for Ruby2JS—while significantly reducing the scope of the project down to what (in my opinion) it is best suited for and what I best understand. And beyond that, any additional features are quite welcome to be handled via Ruby2JS “plugins” by others in the community.

The Future of Ruby on the Frontend

This brings me to my final and most general point regarding where we, the Ruby web developer community, are headed.

I have become fairly convinced with the release of Ruby 3.2 and its brand-new WebAssembly support that the future of Ruby on the frontend is Wasm. This means I forsee a day when writing actual Ruby code and directly executing it in the browser will be feasible for a considerable number of ambitious projects.

In effect, this will render both Ruby2JS and Opal obsolete. Why try to fiddle with various compile-to-JavaScript languages and syntaxes when you can simply write Ruby and run it?! That’s obviously the ideal, even if today there are significant hurdles to overcome (most notably large Wasm payloads and simplistic Ruby<->JS APIs).

So I look forward to that day, even if it’s still a few years away. In the meantime, I’m thrilled I can continue to write frontend code in a Ruby-like way using Ruby2JS. And I hope you are as well.

Questions? Ideas? Suggestions? Hop in our GitHub Discussions and let us know! And if you find an issue with Ruby2JS 5.1, please file an issue report so we can make Ruby2JS. Better yet, if you’d like to become a contributor yourself to Ruby2JS, we welcome your involvement and support!

Register

2021-03-22T00:00:00-04:00

Originally, CoffeeScript had a coffeescript/register module, which would automatically compile CoffeeScript files on the fly.

Originally, Babel later adopted it, producing the @babel/register module, which will automatically compile .es6, .es, .jsx, .mjs, and .js files the fly.

Now, Ruby2JS has adopted the idea, and in fact uses the same hook, and makes available the @ruby2js/register module, which will automatically compile .rb files on the fly.

Demonstration

Let’s start with the simple and somewhat canonical greet function in Ruby:

# greet.rb
def greet(name)
  puts "Hello #{name}!"
end

Now add a main program, in JavaScript, which registers and configures Ruby2JS, and then calls out to the above script:

// main.js
require('@ruby2js/register')({
  options: {
    eslevel: 2021,
    autoexports: 'default',
    filters: ['cjs', 'functions']
  }
})

const greet = require('./greet')

greet('World')

All that’s left is to install the module and go:

yarn add @ruby2js/register
node main.js

Enjoy!

New Stimulus Design Pattern?

2021-02-24T00:00:00-05:00

As far as I know, this is a new design pattern for Stimulus. At the very least, it isn’t something I was able to readily find with Google searches.

First, let’s gets some standard stuff out of the way. The Ruby2JS.com is built using the Bridgetown static site generator. Opal is used to generate the bulk of the scripts to be executed. HTTP caching ensures that these scripts are only downloaded when they change. Turbo ensures that these scripts are only loaded once per site visit. Stimulus associates HTML elements with controllers.

All standard stuff so far.

Ruby2JS.com has three controllers on the page. The first is a Ruby editor. The second is a read-only JavaScript view. And the third is invisible, but runs the JavaScript which outputs to the console log. Other pages have these same three controllers with different arrangements and/or different data, for example the Stimulus introduction and the React Simple Component. The Ruby2JS Demo has a Ruby editor and a JS ouput, but doesn’t have a results controller and adds an options controller.

The source to the controllers can be found in GitHub. Unsurprisingly given that these controllers support the Ruby2JS site, they are written in Ruby.

But that’s not the unique design pattern part.

Look at a Ruby editor on any of the pages mentioned. There isn’t really any Actions, Targets, Values, or CSS Classes to speak of.

Instead, updates made in the Ruby editor are sent to other controllers. A global overview of the design of these pages: the options controller on the demo page will update the Ruby controller. The Ruby controller will update both the JavaScript and evaluation results controllers. And there is even a case where the evaluation results controller will update the Ruby controller, but we will get to that in a minute.

All of this is accomplished by subclassing a common base class and overridding the source method with calls to a findController method. The findController method unsurprisingly searches the application.controllers array. This base class also takes care of connecting sources with targets indpendent of the order in which the controllers connect.

Once a source is paired with potentially multiple targets, messages pass via standard method calls and/or attribute accessors (getters and setters in JavaScript terms).

As an example, here are the lines of code where Ruby2JS.convert is called and the resulting JavaScript is sent to each target.

The JSController’s implementation of the contents= method will dispatch the content to the jsEditor.

The EvalController’s implementation of the contents= method will load the script into a script element and append it to the document.

An interesting detail: if you bring up the Stimulus Introduction page and click on the JavaScript tab you will see different results in Safari than you would in see in Chrome, Firefox, or Microsoft Edge. Safari doesn’t yet support static public fields, so an assignment statement after the class definition is used instead.

The way this works is that the Ruby souce code is initially converted to JavaScript using the ES2022 option, and the results are sent to the evaluation controller. The evaluation controller captures the syntax error and given that this occurred on the very first update it will update the options in the Ruby Controller, triggering another conversion, the results of which are sent to both the JS and Eval controllers.

While this usage is quite different than the traditional application of Stimulus, the end result is comparable: a site consisting entirely of static HTML augmented with a small number of data- attributes that cause the controllers to activate.

I’m quite curious if others have seen this usage of Stimulus before, if they find it useful, or have any suggestions.

New live demo

2021-01-19T00:00:00-05:00

Check it out here.

Because the conversion from Ruby to JavaScript is fast and runs right in your browser, this demo will update the converted output keystroke-by-keystroke as you enter your code. Find and fix your syntax errors, select the right filters and options, and ensure the JavaScript to be generated is what you intend before you commit your code.

Or just use it to learn idiomatic equivalents to common Ruby language patterns. Just be sure to select a modern eslevel, and liberally add filters, particularly filter functions.

Under the covers, it is running the same ruby2js code, just converted from Ruby to JavaScript using the excellent Opal converter.

See a conversion that either isn’t quite right or isn’t the best it can be? Let us know!

Why Opal? Because it is the right tool for this job.

Ready to Give Ruby2JS a Try?

React filter documentation has landed!

2021-01-06T00:00:00-05:00

While filters can do one-for-one transformations, they can also do much more. The react filter will, for example, do the following:

Support multiple syntaxes for HTML, including JSX and direct calls to React.createElement.
Unifying all of the mechanisms to initialize, reference, and update state with assignments and references to instance variables.
Automatically bind all event handlers.
Eliminate the need to create event handlers for controlled components.

See the documentation for more details and live examples.

Welcome to the New Ruby2JS Website

2020-12-29T00:00:00-05:00

There’s only so much you can do with a README on GitHub and then it’s time for an upgrade. 😎

So here it is! The brand new Ruby2JS documentation site. Now that we have a spiffy new home on the interwebs, we’ll be polishing up and adding additional documentation and examples, as well as posting news updates as features and improvements get added to the project.

Many thanks to Sam Ruby for giving me (Jared) so much runway to transition everything over to the new site (and a new org on GitHub!). Lots more exciting news in store for 2021!

Ready to Give Ruby2JS a Try?