Opal Compiler

3.0.0 verified Fri May 01 auth: no javascript

Transpile Ruby code to JavaScript in Node.js using the Opal Ruby-to-JS compiler. Current stable version 3.0.0 is based on Opal 1.7.3 and requires Node >=16. Release cadence is irregular. Unlike browser-focused Opal builds, this package provides a Node-native API (Builder) to compile Ruby files programmatically. Key differentiator: direct Node.js integration with no separate runtime required, supporting modern ESM patterns in v3.

Common errors

error TypeError: Builder is not a constructor ↓

cause Using new Builder() instead of Builder.create()

fix

Use Builder.create() static factory method.

error Error: Cannot find module 'opal-compiler' ↓

cause Package not installed or wrong import path

fix

Run 'npm install opal-compiler' and ensure import/require path matches.

error Opal is not defined ↓

cause Opal global not set, possibly because package not imported or CJS/ESM mismatch

fix

Import the package at top level (import 'opal-compiler' or require('opal-compiler')) before using Opal.

error Error: 'require.resolve.paths' is not a function ↓

cause Using a very old Node version (<16) with v3

fix

Upgrade Node to >=16.

Warnings

breaking v3.0.0 drops support for Node <16; older versions will fail. ↓

fix Upgrade Node.js to >=16.

breaking ESM-only imports in v3; CommonJS require is deprecated. ↓

fix Use import syntax or enable ESM in your project.

deprecated Builder.create() in v2 used a different constructor signature. ↓

fix Use the current Builder.create() API as documented.

gotcha Opal global is auto-set; do not assign it manually. ↓

fix Simply import the package; Opal is available on window/globalThis.

gotcha Build result may need Opal runtime to execute; ensure opal package is installed. ↓

fix Install opal as a dependency (npm install opal).

Install

npm install opal-compiler

yarn add opal-compiler

pnpm add opal-compiler

Imports

Builder

wrong

const Builder = require('opal-compiler').Builder

correct

import { Builder } from 'opal-compiler'

ESM-only since v3; CJS require still works but is deprecated.

default (Opal global)
wrong
```
const Opal = require('opal-compiler')
```
correct
```
import 'opal-compiler'
```
The Opal global is automatically set; direct import without binding is sufficient.
Builder.create
wrong
```
new Builder()
```
correct
```
Builder.create()
```
Builder.create() is a static factory; constructor is not exposed.

Quickstart

Transpile a Ruby file to JavaScript and print the compiled output.

import { Builder } from 'opal-compiler';
const builder = Builder.create();
const result = builder.build('hello.rb').toString();
console.log(result);