TutorialKit.rb: interactive Ruby gem docs powered by Wasm

Talk from RubyKaigi 2026, Hakodate, April 22, 2026.

What if trying a Ruby gem was as easy as opening a web page — no local setup, no bundle install, no version headaches? TutorialKit.rb enables interactive, runnable tutorials for Ruby gems directly in the browser by combining Ruby on WebAssembly with an in-browser development runtime. This talk covers the Ruby Association Grant-funded work behind it: the browser → WebContainer → ruby.wasm architecture, the Ruby-to-WebContainer HTTP bridge, and the build and distribution pipeline.

Transcript

3. https://www.ruby.or.jp/en/news/20251030
7. https://my-ruby-tutorial.com Browser runtime Rails app Ruby interpreter Filesystem Database
8. Cheap authoring More tutorials Growing ecosystem More users
9. User Builder Magician
10. TODO: the talk Framework overview Tutorial capabilities Framework capabilities Framework architecture Ruby Association Grant work What comes next
11. TODO: the talk Framework overview Tutorial capabilities Framework capabilities Framework architecture Ruby Association Grant work What comes next : "Let's jump in!"
13. rails-tutorial.evilmartians.io
14. tutorial.actionpolicy.evilmartians.io
15. TODO: the talk Framework overview Tutorial capabilities Framework capabilities Framework architecture Ruby Association Grant work What comes next : "Let's build!"
17. my-tutorial/ ├── src/ │ ├── content/tutorial/ │ │ ├── 1-getting-started/ │ │ └── meta.md │ └── templates/default/ │ ├── app/ │ ├── config/ │ └── Gemfile ├── ruby-wasm/ │ ├── Gemfile │ └── boot.rb # lesson content (MDX) # the Rails app (runs in the browser) # the Rails app for ruby.wasm module
18. ├── package.json └── astro.config.mjs 1-welcome/ ├── content.mdx # lesson text ├── _files/ # starting state │ ├── app/controllers/pages_controller.rb │ ├── app/views/pages/home.html.erb │ └── config/routes.rb └── _solution/ ├── app/controllers/pages_controller.rb # finished state ├── app/views/pages/home.html.erb └── config/routes.rb
19. content.mdx --type: lesson title: Welcome focus: /app/controllers/pages.rb previews: - [3000, "Rails app"] filesystem: watch: true --- # sidebar label # file opened in editor # live-preview port # reflect edits live # Welcome This lesson covers the basics: - how Rails routes a request - how a controller responds - how ERB renders a view Edit the controller to return a greeting, then reload the preview.
20. npm run pack:wasm npm run dev # package Ruby gems # start the dev server
21. ❤️
22. my-tutorial/ ├── AGENTS.md └── .agents/ └── skills/ ├── tutorial-quickstart/ ├── tutorial-content-structure/ ├── tutorial-lesson-config/ ├── rails-lesson-recipes/ ├── rails-file-management/ └── rails-wasm-author-constraints/
24. Deploy
25. TODO: the talk Framework overview Tutorial capabilities Framework capabilities Framework architecture Ruby Association Grant work What comes next : "Let me show you how it works!"
26. TODO: Rails in a browser Ruby interpreter Static filesystem Dynamic filesystem Processes & shell Web server Database UI
27. WebAssembly
28. WebAssembly System Interface
29. https://github.com/ruby/ruby.wasm
30. TODO: Rails in a browser Ruby interpreter Static filesystem Dynamic filesystem Processes & shell Web server Database UI
31. wasi-vfs
32. https://github.com/palkan/wasmify-rails
33. bin/rails wasmify:build
34. TODO: Rails in a browser Ruby interpreter Static filesystem Dynamic filesystem Processes & shell Web server Database UI
35. 2-layer filesystem /usr/ 🔨 BUILD TIME ▶️ RUNTIME ruby.wasm host FS stdlib /workspace/ /rails-vm/ user app gems · boot · Gemfile wasi-vfs · read-only WASI preopen · read-write
37. https://webcontainers.io
38. https://my-ruby-tutorial.com Web Application (main JS thread) WebContainer API Client ↓ (shell I/O) Terminal UI (files) Editor (HTTP) Preview Iframe WebContainer runtime (isolated Web Worker) Node.js Runtime (V8-based) ↓ (HTTP Traffic) ↔ Virtual File System (in memory) Service Worker (browser-level network proxy)
39. TODO: Rails in a browser Ruby interpreter Static filesystem Dynamic filesystem Processes & shell Web server Database UI
40. Preview iframe Express (WebContainer) JS globals Ruby (Rack) GET /articles req-42 = {method, path, headers, body} res-42 = {} evalAsync(handle("42")) read req-42 build Rack env · dispatch res-42 ← {status, headers, body} promise resolves HTTP response Preview iframe Express (WebContainer) JS globals Ruby (Rack)
41. TODO: Rails in a browser Ruby interpreter Static filesystem Dynamic filesystem Processes & shell Web server Database UI
42. https://github.com/electric-sql/pglite
43. https://github.com/stackblitz/tutorialkit
45. TutorialKit UI WebContainer runtime Rackcompatible web server PGLite Lesson files Terminal UI ruby.wasm Gems Native extensions System tools Ruby VM: WASM + WASI App code Preview Iframe
46. TODO: the talk Framework overview Tutorial capabilities Framework capabilities Framework architecture Ruby Association Grant work What comes next
47. Grant goals TutorialKit 1.0.0-rc1 Action Policy tutorial Outbound HTTP ruby.wasm build optimization
49. runruby.dev
50. class Gem::Request def perform_request(req) response = JS.eval(<<~JS).await return fetch(#{uri.to_s.to_json}, { ... }) .then(response => { ... }) JS Net::HTTPResponse.new("1.1", response[:status], "OK").tap do |r| r.body = response[:body] response[:headers].each { |k, v| r[k] = v } end end end
51. Net::HTTP.prepend(Module.new do def request(req, body = nil, &block) uri = reconstruct_url(req) response = WasmHTTP::Connection.new.request( uri, method: req.method, headers: headers(req), body: req.body ) yield response if block # Faraday's :net_http adapter reads status here response end def connect; end def do_start; @started = true; self; end def do_finish; @started = false; end end)
53. https://ruby-llm-tutorial.fly.dev/1-ruby-llm-demo/1-chat-with-llm/
54. Grant goals TutorialKit 1.0.0-rc1 Action Policy tutorial Outbound HTTP ruby.wasm build optimization
56. github.com/kateinoigakukun/mastodon.wasm
58. : "Something is off..."
59. WASI preopen (fd → /gems) Ruby VM (WASM) JS host require "rails" fd_stat(fd, "rails.rb") WASM ↔ JS boundary — imported JS fn stat(path) WebContainer FS lookup stat struct return value Ruby VM (WASM) WASI preopen (fd → /gems) JS host
61. npm run pack:wasm npm run build:wasm # pure-Ruby gems only: seconds # C extensions changed: minutes
62. : "Why keep the old one?"
63. gem install Gem author Ruby runtime cross-compile per platform pick matching .gem bcrypt_ext.so (x86_64-linux) require "bcrypt" dlopen("bcrypt_ext.so") native functions available gem install Ruby runtime
65. TODO: the talk Framework overview Tutorial capabilities Framework capabilities Framework architecture Ruby Association Grant work What comes next
67. WASI Preview 1 — today WASI Preview 2 — ahead Files, clocks, random, stdio ❌ Sockets ❌ Threads Everything in P1 ✅ Native sockets ✅ Better component model ✅ Standardized capabilities →
68. Two gates before we can experiment 🔬 ruby.wasm WASI P2 support Experimental branch already exists. Soft blocker. ⏳ WebContainer WASI P2 support StackBlitz would need to add support. External dependency.
69. TODO: drop WebContainer Swap HTTP serving to a Service Worker (mastodon.wasm pattern) Build a virtual filesystem + editor sync Terminal + process layer ( rails , bundle , etc.)
70. : "I learned something." : "Shipped." : "…still more to figure out."
71. Kudos Yuta Saito Vladimir Dementyev Svyatoslav Kruykov Grant mentor Rails tutorial POC runruby.dev ruby.wasm Action Policy tutorial JS-bridge HTTP pattern "Rails on Wasm" book
73. https://github.com/Bakaface/tutorialkit.rb
74. 🙏