vite-plugin-opal

Vite plugin for compiling Ruby files using Opal. Write Ruby code and run it in the browser with Vite's fast development experience.

Features

- ⚡️ Fast Compilation: Compile .rb files on-demand during development
- 🔥 Hot Module Replacement: Instant updates when Ruby code changes
- 🗺️ Source Maps: Debug Ruby code in browser DevTools
- 📦 Automatic Runtime: Opal runtime is injected automatically
- 🔍 Dependency Tracking: Handles require statements and tracks dependencies
- 💾 Smart Caching: Caches compilation results based on file modification time

Installation

``bash
npm install vite-plugin-opal


or

pnpm add vite-plugin-opal

or

yarn add vite-plugin-opal
`

You also need to have Ruby and the opal-vite gem installed:

`bash
gem install opal-vite


or add to Gemfile


gem 'opal-vite'
`

Usage

$3

`typescript
import { defineConfig } from 'vite'
import opal from 'vite-plugin-opal'

export default defineConfig({
plugins: [
opal({
loadPaths: ['./src'],
sourceMap: true,
debug: false
})
]
})
`

$3

`ruby
puts "Hello from Ruby!"

class Counter
def initialize
@count = 0
end

def increment
@count += 1
puts "Count: #{@count}"
end
end

counter = Counter.new
counter.increment
counter.increment
`

$3

Important: Due to Vite's module resolution, you cannot directly import .rb files in HTML. Use a JavaScript loader:

`javascript
// src/main_loader.js
import './main.rb'
`

$3

`html








Opal + Vite





`

Options

$3

- Type: string
- Default: 'opal-vite'

Path to the opal-vite gem. Use a relative or absolute path for local development.

$3

- Type: boolean
- Default: true

Enable source map generation for debugging.

$3

- Type: string[]
- Default: ['./src']

Directories to search for Ruby files when using require.

$3

- Type: boolean
- Default: false

Enable arity checking in compiled code.

$3

- Type: boolean
- Default: true

Enable object freezing for immutability.

$3

- Type: boolean
- Default: false

Enable debug logging.

How It Works

$3

1. Vite dev server starts and loads the plugin
2. When a .rb file is imported, the plugin's load hook is triggered
3. Plugin spawns a Ruby child process to compile the file using Opal
4. Compiled JavaScript is returned with source maps
5. HMR watches for file changes and invalidates the module
6. Browser receives update and hot-reloads the module

$3

1. vite build processes all entry points
2. Ruby files are compiled to optimized JavaScript
3. Source maps can optionally be generated
4. Assets are fingerprinted and added to manifest

Advanced Usage

$3

`ruby


src/lib/helper.rb

module Helper
def self.greet(name)
"Hello, #{name}!"
end
end

src/app.rb

require 'lib/helper'

puts Helper.greet("World")
`

$3

`ruby
require 'native'

Access DOM


element = Native(document.getElementById('app'))
element[:textContent] = 'Updated by Ruby!'

Use JavaScript libraries

console.log('From Ruby!')
`

$3

The plugin automatically tracks dependencies and ensures proper load order:

`ruby


lib/calculator.rb

class Calculator
def add(a, b); a + b; end
end

lib/formatter.rb

require 'lib/calculator'

class Formatter
def format_sum(a, b)
calc = Calculator.new
"#{a} + #{b} = #{calc.add(a, b)}"
end
end

app.rb

require 'lib/formatter'
puts Formatter.new.format_sum(5, 3)
`

Troubleshooting

$3

Ensure Ruby is in your PATH:

`bash
which ruby
ruby --version
`

$3

Install the opal-vite gem:

`bash
gem install opal-vite
`

$3

- Ensure Vite dev server is running
- Use JavaScript loaders for .rb files
- Check browser console for errors

$3

- Check Ruby syntax with ruby -c yourfile.rb`
- Verify all required files are in load paths
- Some Ruby features are not supported by Opal

Related Projects

- opal-vite - Core Ruby gem
- opal-vite-rails - Rails integration
- Opal - Ruby to JavaScript compiler

License

MIT