Repository navigation
Rack Middleware and HMR Dev Mode
Hakan Batuhan Kaba edited this page Nov 13, 2026
·
1 revision
When a Ruby gem ships an embedded Vite, Next.js, or Angular web interface, gem authors need two distinct workflows:
-
Local Development: Instant Hot Module Replacement (HMR) against a live dev server (
localhost:5173,:3000,:4200). -
Production Gem Distribution: Fast, secure, zero-Node.js static serving directly out of the installed
.gem.
RubyToFaster solves both with zero external dependencies.
RubyToFaster::Middleware is compatible with both Rack 2.x and Rack 3.x (Rails Engines, Sinatra, Hanami, Roda, Puma, Falcon):
require "rubytofaster"
use RubyToFaster::Middleware,
root: File.expand_path("../public/vite", __dir__),
url_prefix: "/studio/assets",
spa_fallback: true, # Serves index.html for client-side Angular/React/Vue routes
index_file: "index.html"-
Zero-CPU
.gzNegotiation: Automatically serves pre-compressed<asset>.gzsidecars generated bypkg.precompress_assetswhen the browser sendsAccept-Encoding: gzip, settingContent-Encoding: gzipandVary: Accept-Encoding. -
Immutable Fingerprinted Caching: Emits
Cache-Control: public, max-age=31536000, immutablefor hashed Vite/Angular chunks and/_next/static/*assets. -
Conditional
ETag(304 Not Modified): Eliminates redundant HTML/manifest transfers. -
Next.js Clean Export Routes: Automatically resolves
/docstodocs.htmlordocs/index.html. -
Hardened Path Jail: Blocks
..,\, NUL bytes, and symlinks with403 Forbidden, and setsX-Content-Type-Options: nosniff.
Both RubyToFaster::AssetManifest and the generated Ruby helper (pkg.generate_asset_helper) inspect dev_server: (defaulting to ENV["RTF_DEV_SERVER"]).
Start your Vite dev server during gem UI development:
RTF_DEV_SERVER=http://localhost:5173 bundle exec rackupIn your ERB/Slim/Phlex template, keep the exact same helper call for both development and production:
<%= MyEngine::Assets.html_tags("src/main.ts", framework: :vite, url_prefix: "/studio/assets") %>-
When
RTF_DEV_SERVERis set: Emits<script type="module" src="http://localhost:5173/@vite/client">+<script type="module" src="http://localhost:5173/src/main.ts">. -
When packaged in production: Emits fingerprinted
<link rel="stylesheet">and<script type="module">tags from the embedded manifest.
RubyToFaster — Minimalist script-first Ruby gem build system by HNM Labs · MIT License · Security Policy