Opal is a Ruby to JavaScript source-to-source compiler, shipping with an implementation of the Ruby corelib and stdlib.
These guides are organised by what you are trying to do:
| If you want to… | Go to |
|---|---|
| Learn Opal by building something | Tutorial |
| Accomplish a specific task | How-to guides |
| Look up a flag, option, or API | Reference |
| Understand how Opal works | Explanation |
| Contribute to Opal itself | Contributing |
Upgrading from Opal 1.x? Start with the 2.0 migration guide.
Start here if you are new. Learning-oriented, meant to be followed start to finish.
Install Opal, compile your first Ruby file, and run it in a browser and on Node.js.
Task-oriented recipes. Each one solves a single problem and assumes you already know the basics.
The most basic setup for a static Opal powered website that can be hosted anywhere.
Build your project into a directory of ES modules — the recommended way to build an Opal project.
Define where Opal should look for Ruby files at build time.
Debug your Ruby sources directly in the browser devtools.
Use opal-rails to make Opal your JavaScript compiler.
Serve Opal applications through Sinatra and opal-sprockets.
Serve Opal applications from Roda.
Configure the long-lasting asset handler to work with Opal.
Write specs for your Opal code and run them on Node.js or in a browser.
Run your Opal application in a headless browser from the CLI instead of Node.js.
Work with template libraries in Opal, including sharing templates with the server.
Parse and run Ruby scripts inside a browser or any supported JavaScript environment.
Make your gem work in Opal and differentiate code for the JavaScript environment.
The opal-jquery wrapper around the popular library.
Information-oriented. Dry, complete, and meant for looking things up.
Every opal command-line flag, what it does, and its default.
Every Opal::Config option, its type, and its default.
Every available CLI runner, how to select it, and what it requires.
Every breaking change between Opal 1.x and 2.0, with old and new code side by side.
How each part of Ruby maps to JavaScript internally, and how to cross the boundary in both directions using raw interfaces.
How to reach the JavaScript environment from Ruby code.
Special directives that optimize or enhance the compiled output.
Things that are difficult, impossible, or outright incompatible with a JavaScript environment.
Implementation notes on the CDP interface shared by the browser runners.
Understanding-oriented. Background and design rationale, no step-by-step instructions.
The stages a Ruby file passes through on its way to JavaScript.
How a require string becomes a file at compile time and a module at runtime, and
what a leading ./ does.
How Opal makes native JavaScript classes behave like Ruby ones.
How Opal supports JavaScript async/await, and how it lets you avoid explicit callbacks.
How Opal's promise implementations relate to native JavaScript promises.
(WIP) How encoding is handled in Opal, in the browser and in the compiler.
For people working on Opal itself. See also HACKING.md for development environment setup, and CONTRIBUTING.md for the process.
A step-by-step guide to releasing a new version of Opal.
Guides for earlier releases are available here. You are encouraged to help improve these guides — if you spot a typo, a factual error, or something missing, please open a pull request.
Pages moved. These guides were previously a flat list; they now live under
tutorial/,how-to/,reference/,explanation/andcontributing/. If you followed a link to a page that no longer resolves, find it in the index above. Guides published under a released version keep their original addresses, so only links to themasterguides are affected.upgrading.html, which only covered v0.8 → v0.9, was replaced by the 2.0 migration guide.