[Inertia 3.x] SSR in development & caching

[skryukov]

Summary

• SSR in dev mode: When Vite dev server is running, SSR requests route to /__inertia_ssr (exposed by @inertiajs/vite) on the Vite dev server instead of the production SSR endpoint — no separate SSR server needed during development
• Better error handling: Structured SSRError with type, hint, source location; configurable on_ssr_error callback and ssr_raise_on_error option
• Bundle detection: Skip SSR HTTP calls entirely when the SSR bundle doesn't exist on disk
• SSR response caching: Cache SSR responses via Rails.cache to avoid redundant renders for identical pages

Usage

SSR in development — works automatically with vite_rails and rails_vite. Requires ssr_enabled to be enabled, and endpoint to be set on Vite plugins side.

Caching:

# Global — cache all SSR responses (uses Rails.cache)
InertiaRails.configure do |config|
  config.ssr_cache = true
  # or with options:
  config.ssr_cache = { expires_in: 1.hour }
  # or with a lambda (evaluated in controller context):
  config.ssr_cache = -> { { expires_in: 1.hour } }
end

### Per-render override
render inertia: 'Page', props: { ... }, ssr_cache: false

Caching is automatically disabled when Vite dev server is running.

Error handling:

InertiaRails.configure do |config|
  # Raise SSRError instead of falling back to CSR (useful in dev/CI)
  config.ssr_raise_on_error = true

  # Custom error callback (always called, even when not raising)
  config.on_ssr_error = ->(error, page) {
    Sentry.capture_exception(error)
  }
end

Bundle detection:

InertiaRails.configure do |config|
  # Skip SSR when bundle doesn't exist (avoids connection errors)
  config.ssr_bundle = Rails.root.join('public/ssr/ssr.js')
  # or multiple paths:
  config.ssr_bundle = ['public/ssr/ssr.js', 'public/ssr/ssr.mjs']
end