Integrate Opal with Vite - Write Ruby code and run it in the browser with Vite's lightning-fast development experience.
- ⚡️ Fast Development: Leverage Vite's instant server start and HMR
- 💎 Ruby in Browser: Write Ruby code that compiles to JavaScript via Opal
- 🔥 Hot Module Replacement: See changes instantly without page reload
- 🗺️ Source Maps: Debug your Ruby code in the browser DevTools
- 📦 Auto Runtime Loading: Opal runtime loads automatically
- 🚂 Rails Integration: Seamlessly integrate with Rails applications
This is a monorepo containing:
- packages/vite-plugin-opal: Vite plugin for Opal compilation
- packages/opal-language-server: LSP server for IDE integration (VS Code, IntelliJ, Vim, etc.)
- packages/vscode-opal-vite: VS Code extension for Opal development
- gems/opal-vite: Ruby gem for Opal-Vite integration
- gems/opal-vite-rails: Rails integration gem
- examples/standalone: Standalone SPA example
- examples/stimulus-app: Stimulus + Opal integration example
- examples/turbo-app: Turbo + Opal integration example
- examples/practical-app: Full-featured Todo app with real-world patterns
- examples/rails-app: Rails integration example (coming soon)
The fastest way to see Opal + Vite in action:
# Clone the repository
git clone https://github.com/your-org/opal-vite.git
cd opal-vite
# Install root dependencies
pnpm install
# Navigate to practical-app example
cd examples/practical-app
# Install dependencies
bundle install
pnpm install
# Run development server
pnpm devOpen http://localhost:3002 to see a full-featured Todo app built with Ruby!
# Install dependencies
pnpm install
cd examples/standalone
pnpm install
# Run development server
pnpm dev# Add to Gemfile
gem 'opal-vite-rails'
# Install
bundle install
bundle exec rails generate opal_vite:install
# Start servers
bin/vite dev # In one terminal
rails server # In another terminalimport { defineConfig } from 'vite'
import opal from 'vite-plugin-opal'
export default defineConfig({
plugins: [
opal({
loadPaths: ['./src'],
sourceMap: true
})
]
})puts "Hello from Ruby!"
class Greeter
def initialize(name)
@name = name
end
def greet
puts "Hello, #{@name}!"
end
end
greeter = Greeter.new("World")
greeter.greet<!DOCTYPE html>
<html>
<head>
<title>Opal + Vite</title>
</head>
<body>
<h1>Opal + Vite</h1>
<script type="module" src="/src/main.rb"></script>
</body>
</html>-
vite-plugin-opal - Vite plugin for compiling Ruby files
- Plugin configuration options
- API reference
- Advanced usage examples
-
opal-vite - Core Ruby gem
- Compiler API
- Configuration
- CLI commands
-
opal-vite-rails - Rails integration
- Installation guide
- View helpers
- Rake tasks
- Production deployment
Explore our examples to learn different integration patterns:
| Example | Description | Tech Stack | Features | Port |
|---|---|---|---|---|
| standalone | Basic Vite + Opal setup | Opal + Vite | Simple compilation, Multi-file deps, HMR | 3000 |
| stimulus-app | Stimulus integration | Opal + Stimulus + Vite | Stimulus controllers in Ruby, Counter demo | 3001 |
| turbo-app | Turbo integration | Opal + Turbo + Vite | Turbo Frames, Turbo Streams in Ruby | 3002 |
| practical-app | Real-world Todo app | Opal + Stimulus + Vite | CRUD, LocalStorage, Modals, Toasts, Animations | 3002 |
| rails-app | Rails integration | Rails + Opal + Vite | View helpers, Asset pipeline | 3000 |
Basic Vite + Opal setup demonstrating:
- Simple compilation
- Multi-file dependencies
- HMR demonstrations
Integration with Stimulus framework:
- Write Stimulus controllers in Ruby using
opal_stimulusgem - Counter application with increment/decrement
- Shows Ruby → JavaScript controller compilation
Integration with Turbo for dynamic updates:
- Turbo Frames for partial page updates
- Turbo Streams for real-time updates
- Counter with server-less dynamic updates
- All in Ruby without writing JavaScript
Full-featured Todo application demonstrating real-world patterns:
- CRUD Operations: Create, read, update, delete todos
- LocalStorage: Data persistence across page reloads
- Form Validation: Real-time validation with visual feedback
- Modal Dialogs: Edit todos in animated modal
- Toast Notifications: Success/error messages
- Animations: Smooth transitions throughout
- Cross-controller Communication: CustomEvent pattern
- Template Cloning: Dynamic content generation
Full Rails integration:
- Rails setup
- View integration
- Production build
-
Development Mode:
- Vite dev server watches
.rbfiles - When imported, the plugin calls Ruby compiler via
child_process - Compiled JavaScript is returned with source maps
- HMR updates browser when Ruby files change
- Vite dev server watches
-
Production Mode:
vite buildcompiles all.rbfiles to optimized JavaScript- Source maps can be generated for debugging
- Assets are fingerprinted and added to manifest
-
Rails Integration:
- Development: Proxies to Vite dev server for HMR
- Production: Loads precompiled assets from manifest
- View helpers automatically handle both modes
Due to Vite's module resolution, .rb files cannot be directly imported in HTML. Instead, use a JavaScript loader:
// main_loader.js
import './main.rb'<script type="module" src="/src/main_loader.js"></script>The Opal runtime is automatically injected via a virtual module /@opal-runtime. This provides Ruby core classes and standard library.
Configure load paths to resolve require statements:
opal({
loadPaths: ['./app/opal', './lib/opal']
})Files in these directories can be required without specifying the full path.
- Ensure Vite dev server is running
- Check that you're using JavaScript loaders for
.rbfiles - Verify the plugin is in
vite.config.ts
- Check Ruby syntax with
ruby -c file.rb - Verify all required files are in load paths
- Some Ruby features are not supported by Opal (see Opal docs)
- Enable caching in development (automatic)
- For large projects, consider splitting into smaller modules
- Use
debug: falsein production
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run tests
cd packages/vite-plugin-opal
pnpm test
cd ../../gems/opal-vite
bundle exec rspec
# Run examples
cd examples/standalone
pnpm dev
cd ../rails-app
bin/vite dev
rails server
# Clean build artifacts
pnpm cleanContributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
- Support for more Opal standard library features (v0.3.1: URIHelpers, Base64Helpers)
- Performance optimizations (v0.3.2)
- Better error messages and debugging (v0.3.3: DebugHelpers module)
- Additional Rails integrations (v0.3.4: ActionCable, Turbo modules)
- CDN support for Opal runtime (v0.3.5)
- VS Code extension for
.rbfile support (v0.3.6: LSP server, Syntax highlighting, Diagnostics, Snippets)
MIT