Opal

Opal is a Ruby to JavaScript source-to-source compiler, shipping with an implementation of the Ruby corelib and stdlib.

Write Ruby, run it anywhere JavaScript runs — the browser, Node.js, Deno, Bun, QuickJS.

Why Opal

A real Ruby implementation. Opal ships its own corelib and stdlib and is validated against ruby/spec, the same suite CRuby uses. A JavaScript host imposes limits — those are catalogued in Unsupported Features.
Source-to-source, no runtime interpreter. Ruby compiles to plain JavaScript ahead of time, so there is no VM to download and no interpreter loop at runtime.
Two-way JavaScript interop. Call JS from Ruby and Ruby from JS, and treat native JS classes as Ruby ones. See Interfacing with JavaScript.
Share code between server and client. The same gem, the same objects, the same specs, on both sides of the wire.
It compiles itself. The compiler is written in Ruby and builds to opal-parser.js, so it also runs inside the browser.

Installation

Opal needs Ruby. The gemspec declares >= 2.3; CI exercises Ruby 3.0 through 4.0 and JRuby, so 3.x or newer is the sensible choice.

gem install opal

Or in your Gemfile:

gem 'opal'

This installs the latest release, from the 1.8 series. The master branch is 2.0.0dev and is not yet released; to track it:

gem 'opal', github: 'opal/opal'

Then check it:

opal -v
opal -e "puts 'Hello from Opal'"

The second command prints Hello from Opal — it compiled the Ruby and ran the result on Node.js.

Documentation

Guides — tutorial, how-to guides, reference, and explanation, also rendered at opalrb.com/docs.
Getting Started — the tutorial to follow first.
Migrating to Opal 2.0 — every breaking change from 1.x, with old and new code side by side.
CLI Reference and Runners — every flag and every execution target.
Framework integrations: Rails, Sinatra, Roda, static apps.

Usage

Compiling Ruby with the CLI

Contents of app.rb:

puts 'Hello world!'

Then from the terminal:

opal --compile app.rb > app.js

The Opal runtime is included by default; skip it with --no-opal.

The resulting JavaScript file runs from an HTML page. Set the page encoding to UTF-8 — Opal's string handling depends on it:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <script src="app.js"></script>
  </head>
  <body>
  </body>
</html>

Open the page in a browser and check the JavaScript console.

Compiling Ruby from Ruby

Opal.compile compiles a string of Ruby into a string of JavaScript:

require 'opal'

Opal.compile("puts 'wow'")
# => "Opal.queue(function(Opal) { ... return self.$puts(\"wow\") ... });\n"

That output alone is not runnable — it needs the Opal runtime/corelib. Opal::Builder builds the runtime:

Opal::Builder.build('opal')  # => "(function() { ... })()"

or an entire app, resolving require dependencies:

builder = Opal::Builder.new
builder.build_str('require "opal"; puts "wow"', '(inline)')
File.binwrite 'app.js', builder.to_s  # must use binary mode for writing

Compiling Ruby from HTML

opal-parser evaluates Ruby directly from your HTML files, with no build step:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <script src="https://cdn.opalrb.com/opal/current/opal.js"></script>
    <script src="https://cdn.opalrb.com/opal/current/opal-parser.js" onload="Opal.load('opal-parser')"></script>

    <script type="text/ruby">
      puts "hi"
    </script>
  </head>
  <body>
  </body>
</html>

Open the page and check the JavaScript console.

NOTE: this ships the compiler to the client. It is a fast way to try Opal, not a way to deploy it.

Runtime support

The upcoming 2.0 targets ES2021: compiled output and the Opal runtime assume an ES2021-capable engine, and there is no transpilation fallback. If you need to support an older engine, stay on Opal 1.x. See the migration guide for the full rationale.

That means:

Firefox, Chrome, Safari, Edge — current and previous stable versions
Node.js, Deno, Bun, QuickJS, and more — see Runners

Internet Explorer is not supported. Problems on any engine listed above should be reported as bugs.

Contributing

HACKING.md is the contributor guide — prerequisites, bin/setup, running the spec suites, benchmarking, and profiling:

HACKING.md — development environment and test suites
CONTRIBUTING.md — how to file issues and open pull requests

The short version, once you have cloned the repo:

bin/setup
bundle exec rake

Code layout

lib/ — the Opal parser and compiler. Runs in your Ruby environment, and is also built for the browser as opal-parser.js.
opal/ — the runtime and corelib, written in Ruby and JavaScript. Runs in the JavaScript environment.
stdlib/ — Opal's implementation of Ruby's stdlib (StringScanner, Date, Observable, …). Optional, runs in the JavaScript environment.

Versioning

Opal will broadly follow semver as a version policy, trying to bump the major version when introducing breaking changes. Being a language implementation we're also aware that there's a fine line between what can be considered breaking and what is expected to be "safe" or just "additive". Moving forward we'll attempt to better clarify what interfaces are meant to be public and what should be considered private.

The master branch is currently 2.0.0dev — unreleased. The latest released gem is on RubyGems.