Repository navigation
Troubleshooting and FAQ
Hakan Batuhan Kaba edited this page Nov 13, 2026
·
1 revision
Run rtf build --verbose and inspect .rtf-cache/last-build-trace.json. The Merkle cache invalidates whenever any of the following change:
- Any packaged source file's SHA-256 content digest or executable bit
- Staged Vite, Next.js, or Angular bundle files
-
Gem::Specificationversion, summary, dependencies, or metadata -
SOURCE_DATE_EPOCHor Ruby runtime version
RubyToFaster blocks shell command strings to prevent command injection. Change:
# Disallowed:
pkg.vite root: "frontend", build_command: "npm run build:prod"
# Allowed (safe argv array):
pkg.vite root: "frontend", build_command: ["npm", "run", "build:prod"]Source maps are excluded by default to keep .gem downloads compact and protect source code. Enable them explicitly per adapter:
pkg.vite root: "frontend", out_dir: "dist", mount_to: "public/vite", sourcemaps: trueCan I write staged frontend assets and the generated Ruby helper to disk for local Rails/Rack development?
Yes! By default, RubyToFaster stages frontend bundles in-memory directly into data.tar.gz so your working tree stays clean. Set write_staged_assets = true in gem.build.rb when you also want local copies written to disk:
RubyToFaster.build do |pkg|
pkg.gemspec "my_engine.gemspec"
pkg.write_staged_assets = true
pkg.vite root: "frontend", mount_to: "public/vite"
pkg.generate_asset_helper module_name: "MyEngine::Assets", path: "lib/my_engine/assets.rb"
endAdd actions/cache@v4 pointing at .rtf-cache:
- uses: actions/cache@v4
with:
path: .rtf-cache
key: rtf-${{ runner.os }}-${{ hashFiles('**/*.rb', '**/*.gemspec', '**/package-lock.json') }}RubyToFaster — Minimalist script-first Ruby gem build system by HNM Labs · MIT License · Security Policy