tombolo 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3cacc9db2ac7d8ba235b9b142fcd8ff0b97bff68e85335c621ad305adb55839c
+  data.tar.gz: 04f784cf784897a241fe0b410ab4856214c8ffe6879db882028deeec8adfe591
+SHA512:
+  metadata.gz: 456ea07d98bb2e17a5e7dd33a926383ae84612faa4ec7d9874bb8b960d6ebfc2ece64b7c90ed82af38972a7fc45a874cbc08037e577e0cd9729f0d4268fe79fd
+  data.tar.gz: de35b3d525d13de7535a7e57bd17312263157426ea119c3b96d1008e101c7e89cbf23cd904f21bbfd2416dd060424cb0dd92c868bcfa9a884c78a09276067420

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inge Jørgensen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+# Tombolo
+
+Minimal React component mounting for Rails, inspired by
+[react-rails](https://github.com/reactjs/react-rails).
+
+Tombolo is designed for modern Rails apps using jsbundling-rails and
+propshaft. It provides a `react_component` view helper and optional
+server-side rendering with no asset pipeline integration — just a component
+map and a few lines of JavaScript.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "tombolo"
+# gem "execjs"  # required for server-side rendering
+```
+
+Install the npm package:
+
+```sh
+npm install tombolo
+# or
+pnpm add tombolo
+```
+
+Run the install generator to create a config initializer and SSR entry
+point:
+
+```sh
+bin/rails generate tombolo:install
+```
+
+## Usage
+
+### Rails helper
+
+Render a React component from any view or partial:
+
+```erb
+<%= react_component("Greeting", props: { name: "World" }) %>
+```
+
+### Client-side mounting
+
+Tombolo takes a component map — an object mapping component names to React
+components. The easiest way to create one is a barrel file that re-exports
+your components:
+
+```typescript
+// app/javascript/components/index.ts
+export { Greeting } from "./Greeting";
+export { SearchForm } from "./SearchForm";
+```
+
+Import it and call `Tombolo.start` to mount components on page load:
+
+```typescript
+import * as Tombolo from "tombolo";
+import * as components from "./components";
+
+Tombolo.start(components);
+```
+
+Both `Tombolo.mount` and `Tombolo.unmount` accept an optional `scope`
+parameter to limit operations to a subtree of the DOM:
+
+```typescript
+Tombolo.mount(components, document.getElementById("sidebar"));
+```
+
+#### Turbo
+
+For apps using Turbo, use `Tombolo.mount` and `Tombolo.unmount` directly:
+
+```typescript
+import * as Tombolo from "tombolo";
+import * as components from "./components";
+
+document.addEventListener("turbo:load", () => Tombolo.mount(components));
+document.addEventListener("turbo:before-cache", () => Tombolo.unmount());
+```
+
+### Server-side rendering
+
+Create a server entry point that registers your components:
+
+```typescript
+// app/javascript/prerender.ts
+import { registerServerRenderer } from "tombolo/server";
+import * as components from "./components";
+
+registerServerRenderer(components);
+```
+
+Build it with esbuild (or your bundler of choice) targeting a CommonJS
+output that ExecJS can evaluate.
+
+Then use `prerender: true` in your views:
+
+```erb
+<%= react_component("Greeting", props: { name: "World" }, prerender: true) %>
+```
+
+The default server bundle path is `app/assets/builds/prerender.js`. To
+customize it, add an initializer:
+
+```ruby
+# config/initializers/tombolo.rb
+Tombolo.configure do |config|
+  config.server_bundle = "path/to/your/bundle.js"
+end
+```
+
+## API Reference
+
+### npm
+
+#### `Tombolo.start(components)`
+
+Calls `mount` on `DOMContentLoaded`, or immediately if the DOM is already
+loaded. Convenience function for apps without Turbo.
+
+#### `Tombolo.mount(components, scope?)`
+
+Scans `scope` (default: `document`) for elements with a
+`data-react-component` attribute. For each element, looks up the component
+by name, parses props from `data-react-props`, and mounts it.
+Already-mounted elements are skipped. Missing components log a warning to
+the console.
+
+#### `Tombolo.unmount(scope?)`
+
+Unmounts all tracked React roots within `scope` (default: `document`).
+
+#### `registerServerRenderer(components)`
+
+Assigns a `renderComponent(name, propsJson)` function to `globalThis`,
+making it callable from ExecJS. Used in server entry points for SSR.
+
+### Ruby
+
+#### `react_component(name, props: {}, prerender: false, camelize_props: nil)`
+
+Renders a `<div>` with `data-react-component` and `data-react-props`
+attributes. When `prerender: true`, the component is rendered on the server
+via ExecJS and the HTML is placed inside the div. Pass `camelize_props: true`
+to convert snake_case prop keys to camelCase, or set it globally in the
+configuration.
+
+#### `Tombolo.configure { |config| ... }`
+
+- `config.camelize_props` — Convert snake_case prop keys to camelCase.
+  Default: `false`
+- `config.server_bundle` — Path to the server-side JS bundle for SSR.
+  Default: `"app/assets/builds/prerender.js"`
+
+## Migrating from react-rails
+
+The main difference is the helper signature. react-rails passes props as a
+positional argument, Tombolo uses a keyword argument:
+
+```ruby
+# react-rails
+react_component("Name", { title: "Hello" })
+
+# Tombolo
+react_component("Name", props: { title: "Hello" })
+```
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/rails/generators/tombolo/install/install_generator.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Tombolo
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Creates the Tombolo configuration"
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        copy_file "initializer.rb", "config/initializers/tombolo.rb"
+      end
+
+      def create_prerender
+        copy_file "prerender.ts", "app/javascript/prerender.ts"
+      end
+    end
+  end
+end

data/lib/rails/generators/tombolo/install/templates/initializer.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Tombolo.configure do |config|
+  # config.camelize_props = true
+  # config.server_bundle = "app/assets/builds/prerender.js"
+end

data/lib/rails/generators/tombolo/install/templates/prerender.ts

@@ -0,0 +1,4 @@
+import { registerServerRenderer } from "tombolo/server";
+import * as components from "./components";
+
+registerServerRenderer(components);

data/lib/tombolo/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Tombolo
+  class Configuration
+    attr_accessor :camelize_props, :server_bundle
+
+    def initialize
+      @camelize_props = false
+      @server_bundle = "app/assets/builds/prerender.js"
+    end
+  end
+end

data/lib/tombolo/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "tombolo/view_helper"
+
+module Tombolo
+  class Railtie < Rails::Railtie
+    initializer "tombolo.view_helper" do
+      ActiveSupport.on_load(:action_view) do
+        include Tombolo::ViewHelper
+      end
+    end
+  end
+end

data/lib/tombolo/renderer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+begin
+  require "execjs"
+rescue LoadError
+  raise LoadError,
+        "ExecJS is required for server-side rendering. " \
+        "Add `gem \"execjs\"` to your Gemfile."
+end
+
+module Tombolo
+  class Renderer
+    def initialize
+      @mutex = Mutex.new
+      @context = nil
+    end
+
+    def render(name, props_json)
+      @mutex.synchronize do
+        context.call("renderComponent", name, props_json)
+      end
+    end
+
+    private
+
+    def context
+      @context ||= ExecJS.compile(bundle_source)
+    end
+
+    def bundle_source
+      path = Tombolo.configuration.server_bundle
+      raise "Tombolo server bundle not found: #{path}" unless File.exist?(path)
+
+      console_polyfill + File.read(path)
+    end
+
+    def console_polyfill
+      "var console = { log: function(){}, warn: function(){}, error: function(){} };\n"
+    end
+  end
+end

data/lib/tombolo/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Tombolo
+  VERSION = "0.9.0"
+end

data/lib/tombolo/view_helper.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Tombolo
+  module ViewHelper
+    include ActionView::Helpers::TagHelper
+    include ActionView::Helpers::TextHelper
+
+    def react_component(name, props: {}, prerender: false, camelize_props: nil)
+      camelize = camelize_props.nil? ? Tombolo.configuration.camelize_props : camelize_props
+      props = props.deep_transform_keys { |key| key.to_s.camelize(:lower) } if camelize
+
+      props_json = props.to_json
+      data = { react_component: name, react_props: props_json }
+
+      content = ""
+      if prerender
+        data[:react_prerender] = ""
+        content = Tombolo.renderer.render(name, props_json).html_safe # rubocop:disable Rails/OutputSafety
+      end
+
+      content_tag(:div, content, data:)
+    end
+  end
+end

data/lib/tombolo.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "tombolo/configuration"
+require "tombolo/version"
+require "tombolo/view_helper"
+require "tombolo/railtie" if defined?(Rails::Railtie)
+
+module Tombolo
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def renderer
+      @renderer ||= begin
+        require "tombolo/renderer"
+        Renderer.new
+      end
+    end
+
+    def reset!
+      @configuration = nil
+      @renderer = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: tombolo
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Inge Jørgensen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Drop-in replacement for react-rails with minimal footprint. Provides
+  a view helper and optional SSR via ExecJS.
+email:
+- inge@elektronaut.no
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/rails/generators/tombolo/install/install_generator.rb
+- lib/rails/generators/tombolo/install/templates/initializer.rb
+- lib/rails/generators/tombolo/install/templates/prerender.ts
+- lib/tombolo.rb
+- lib/tombolo/configuration.rb
+- lib/tombolo/railtie.rb
+- lib/tombolo/renderer.rb
+- lib/tombolo/version.rb
+- lib/tombolo/view_helper.rb
+homepage: https://github.com/elektronaut/tombolo
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Minimal React component mounting for Rails
+test_files: []