isorun

Run JavaScript applications in your Rails application.

Features

  • Import JavaScript functions, objects, or just values and use them in Ruby
  • An EMCAScript like Ruby DSL to load modules and import items
  • Automatically converts arguments and return values
  • Send messages between JavaScript<->Ruby (allows to intercept network requests and avoid network round-trips for e.g. API calls)
  • Automatically reload modules when updated in development
  • Automatically extracts state (Apollo) and hydrates client-side
  • Supports server-side rendering of multiple apps on a single page
  • Examples for React, Vue, D3 and a multi-app setup

How to

Plain JavaScript

// module.js
export function say(word) {
  return word;  
}

context = Isorun::Context.new

# import `export function say` from module 
say = context.import(:say).from("./module.js")
say.call("Hello!") # "Hello!"

Simple React app

rails new myproject --javascript esbuild
cd myproject

// package.json
{
  "scripts": {
    "build": "esbuild app/javascript/app.jsx --bundle --sourcemap --outdir=app/assets/builds --public-path=assets",
    "build-server": "esbuild app/javascript/app-server.jsx --bundle --sourcemap --outdir=app/assets/builds --public-path=assets --format=esm"
  }
}

# Procfile.dev
web: bin/rails server -p 3000
js: yarn build --watch
ssr: yarn build-server --watch

# config/initializers/isorun.rb
Isorun.configure do
  # …configure isorun
end

// app/javascript/my_app.jsx
import * as React from "react";
import {hydrateRoot} from "react-dom/client";

import {App} from "./my_app/App.jsx";

const container = document.querySelector('#my_app');
hydrateRoot(container, <App/>);


// app/javascript/my_app-server.jsx
import * as React from "react";
import * as Server from "react-dom/server";

import {App} from "./my_app/App.jsx";

export default async function() {
  return Server.renderToString(<App/>);
}

<!--my_view.html.erb-->
<%= isorun_app("my_app") %>

Ruby and platform support

Ruby versions:

  • 2.7
  • 3.0
  • 3.1.

Platforms and architectures:

  • x86_64-linux
  • x86_64-apple
  • arm64-apple

Demo

You can also check out this demo video on YouTube. It shows how you can utilize isorun to render SVGs with Ruby on the server, utilizing JavaScript and the D3 library.

How to use d3 in Ruby

Why server-side rendering (SSR)?

The fastest way to deliver an application to the user is streaming HTML directly to the browser. The slowest way to deliver an application, is downloading a JavaScript file first, parse and execute it on the client side.

Server-side rendering is taking advantage of the fact that we can render a JavaScript application directly on the server, and stream the resulting HTML directly to the browser. Then we fetch the JavaScript file and eventually the application will (re-)hydrate the already rendered user interface.

You can take this concept even further and make your application work without JavaScript at all, but still use React or Vue (or any other view-controller library) to define your user interface.

Read more: Netflix functions without client-side React, and it's a good thing.

Server-side rendering has a few challenges:

  1. You need something that can compile and run JavaScript
  2. You need to be able to integrate the app with your preferred framework
  3. You need to deal with the reality of frontend clients making network requests and managing state

isorun aims to make it as simple as possible to integrate a JavaScript application into your server-side development and deployment workflow, without changing the development workflow for frontend engineers.

This gem provides a helper that can render a JavaScript application directly in your Ruby process, embedding Google's v8 library via deno_core. You can think of it as running a headless JavaScript browser directly in your Ruby process (threads). Using v8 allows us to completely separate the execution environments between individual renders and therefore prevent any potential Cross-Request State Pollution. It is essentiallly the same as opening many tabs in one browser.

Why SSR for Ruby (on Rails)?

I personally enjoy and use Ruby on Rails a lot, but I like to use some Vue and React for frontend work. The integration of frontend and backend always felt a bit off, and I wanted something that "just works" for most of my use cases.

One goal of isorun is that server-side rendering should feel naturally in Ruby and Rails. A simple tag helper should be enough to render, deliver, and hydrate your complex JavaScript application. And if we want to do something nice with visualization libraries, it should be possible to run any JavaScript program and return the result to the user without spinning up a separate service.

Alternatives

"No" JavaScript

If you want to go all-in on the server side, I highly recommend taking a look at HTML over the Wire, and StimulusReflex.

Run a Node.js, deno, or bun service

isorun does SSR a bit different from how you would do it in a regular Node.js service. In addition to being able to render the application, it also supports more powerful features like network intercepts. This means, that you can directly call into the Ruby process from the JavaScript application and e.g. fetch data from the database. This is helpful for applications that utilize APIs to fetch their data. Even when server-side rendered, these applications issue network requests against the production API endpoints to get access to data. In a lot of cases, we can accelerate this process by forwarding the network requests directly to the target controller/action in Rails.Instead of fetching

Example A React applications queries a Rails GraphQL API

We can override the HttpLink fetch method and utilize the @isorun/rails package to send the HTTP request for the GraphQL API directly to the Ruby process, instead of sending it over the network.

import {apollo} from "@isorun/rails";

import {App} from "../my_app/App.jsx";

const apolloClient = new ApolloClient({
  ssrMode: true,
  cache: new InMemoryCache(),
  link: new HttpLink({
    uri: 'http://localhost:3000/graphql',
    fetch: apollo.fetch
  })
});

Isorun.configure do
  receiver do |request|
    query, variables, context, operation_name = parse(request)

    RailsAppSchema.execute(
      query,
      variables: variables,
      context: context,
      operation_name: operation_name
    )
  end
end

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add isorun

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install isorun

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Examples

When running examples, make sure you are on the exact same Ruby version that you used to build isorun with rake compile. If you are on a different Ruby version you might get weird segfaults, encoding issues, etc. that are impossible to debug.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/eliias/isorun.

License

The gem is available as open source under the terms of the MIT License.