tutorialkit-rb-memtor-report.md

Ruby Association Grant 2025: Mentor Report

• Project: TutorialKit.rb - interactive Ruby tutorials in the browser
• Developer: Albert Pazderin
• Mentor: Yuta Saito

Project overview

TutorialKit.rb is a framework for building interactive Ruby and Rails tutorials that run entirely in the browser using WebAssembly and WebContainers. It generalizes the technology behind Evil Martians' interactive Rails tutorial (rails-tutorial.evilmartians.io), presented at RailsConf 2025, into a reusable open-source framework. The framework is based on a fork of TutorialKit (tutorialkit.dev) from the JavaScript ecosystem, adapted for the Ruby environment.

Achievement of the proposed deliverables

The original grant application proposed three deliverables:

1. A stable, open-source release of TutorialKit.rb
2. Tutorials for popular Ruby libraries and frameworks
3. Exploration of different potential applications of Ruby-in-the-browser infrastructure

All three have been successfully achieved, with several technical contributions that go beyond the original scope.

Framework release

The framework has reached the release candidate stage and is ready for general use. NPM packages are published under the @tutorialkit-rb scope.

A notable achievement is the end-to-end authoring experience: a single npx create-tutorialkit-rb command scaffolds a complete tutorial project with a Rails application, and starter lessons. Pre-built CI/CD pipelines for Netlify and Fly.io handle the entire deployment process including ruby.wasm compilation, so tutorial authors do not need to understand the WebAssembly toolchain at all.

The project also ships with a set of Claude Code skills that help AI coding agents understand TutorialKit.rb's constraints (inherent limitations of WebAssembly-itself), content structure, frontmatter configuration, and assist with tutorial content creation. This is a forward-looking design decision that reflects how much of technical writing is being done today.

Other improvements include Ruby/Rails syntax highlighting, an embed mode for iframes, terminal blocking during preparation commands, and headless smoke tests via node:wasi.

Action Policy tutorial

A complete interactive tutorial for Action Policy (an authorization framework for Ruby/Rails) has been built and published at tutorial.actionpolicy.evilmartians.io. The tutorial exercises many of TutorialKit.rb's capabilities: template and per-lesson file configurations, challenge solutions, test execution, and web server interaction. It serves as both a useful learning resource and a real-world reference implementation for future tutorial authors.

Infrastructure exploration

Alongside framework development, the project tackled two significant technical challenges that were identified during the intermediate report phase.

• HTTP support: WASI Preview 1 provides no socket API, making outbound HTTP requests from browser-based Ruby impossible by default. The project implemented a JS bridge that routes Ruby's Net::HTTP requests through WebContainer's Node.js layer to the browser's Fetch API, along with a Faraday adapter for gem compatibility and a self-deployable Cloudflare Worker template for CORS proxy. A proof-of-concept RubyLLM tutorial was built to validate this approach, demonstrating LLM API calls from a Rails application running entirely in the browser.
• Deferred packing: The intermediate report explored three gem packaging strategies: monolithic build (slow rebuilds but fast boot), tarball distribution (fast rebuilds but slow boot), and runtime bundle (requires a backend). The final report introduces a hybrid approach called "deferred packing": a pre-built base binary containing the Ruby interpreter and C extension gems, with pure-Ruby gems layered on top via wasi-vfs pack. This achieves the best of both worlds: rebuild time drops from minutes to seconds, while boot time stays at 2–5 seconds. This was a well-researched engineering decision backed by careful analysis of the state of the art in ruby.wasm packaging.

Role as mentor

At the beginning of the project, I discussed the initial direction and technical approach with the developer. Albert Pazderin and his colleague Vladimir Dementyev at Evil Martians were already deeply experienced with the ruby.wasm ecosystem and related technologies (WebContainers, PGLite, wasmify-rails), and they drove the project forward autonomously with high velocity and quality. I reviewed the intermediate and final reports and was available for technical questions on WebAssembly/WASI matters.

Conclusion

This project delivered all three proposed outcomes and went further with HTTP support and the deferred packing build strategy. TutorialKit.rb establishes a compelling practical use case for running Rails applications in the browser via ruby.wasm. By making it possible for any gem author to create polished, interactive, zero-install tutorials, the project has the potential to meaningfully contribute to Ruby education and community growth. As WASI Preview 2 matures and WebContainer support evolves, there is significant room for further development.