Inertia Rails Server-Side Rendering (SSR)
Server-Side Rendering pre-renders JavaScript pages on the server, delivering fully rendered HTML to visitors. This improves SEO, enables faster initial page loads, and allows basic navigation even with JavaScript disabled.
When to Use SSR
- SEO-critical pages - Landing pages, blog posts, product pages
- Social sharing - Pages that need proper Open Graph meta tags
- Slow connections - Users see content before JavaScript loads
- Accessibility - Basic functionality without JavaScript
Requirements
- Node.js must be available on your server
- Vue 3.2.13+ (or install
@vue/server-rendererseparately for older versions) - Vite Ruby for build configuration
Setup Steps
1. Create SSR Entry Point
Create app/frontend/ssr/ssr.js:
Vue 3:
import { createInertiaApp } from '@inertiajs/vue3'
import createServer from '@inertiajs/vue3/server'
import { renderToString } from '@vue/server-renderer'
import { createSSRApp, h } from 'vue'
const pages = import.meta.glob('../pages/**/*.vue', { eager: true })
createServer((page) =>
createInertiaApp({
page,
render: renderToString,
resolve: (name) => {
const page = pages[`../pages/${name}.vue`]
if (!page) {
throw new Error(`Page not found: ${name}`)
}
return page
},
setup({ App, props, plugin }) {
return createSSRApp({
render: () => h(App, props),
}).use(plugin)
},
})
)
React:
import { createInertiaApp } from '@inertiajs/react'
import createServer from '@inertiajs/react/server'
import ReactDOMServer from 'react-dom/server'
const pages = import.meta.glob('../pages/**/*.jsx', { eager: true })
createServer((page) =>
createInertiaApp({
page,
render: ReactDOMServer.renderToString,
resolve: (name) => {
const page = pages[`../pages/${name}.jsx`]
if (!page) {
throw new Error(`Page not found: ${name}`)
}
return page
},
setup: ({ App, props }) => <App {...props} />,
})
)
2. Configure Vite Ruby
Update config/vite.json:
{
"all": {
"sourceCodeDir": "app/frontend",
"entrypointsDir": "entrypoints"
},
"development": {
"autoBuild": true
},
"production": {
"ssrBuildEnabled": true
}
}
3. Enable SSR in Rails
Update config/initializers/inertia_rails.rb:
InertiaRails.configure do |config|
# Enable SSR only when Vite is configured for it
config.ssr_enabled = ViteRuby.config.ssr_build_enabled
# SSR server URL (default)
config.ssr_url = 'http://localhost:13714'
end
4. Update Client Entry Point
Modify app/frontend/entrypoints/application.js for hydration:
Vue 3:
import { createInertiaApp } from '@inertiajs/vue3'
import { createSSRApp, h } from 'vue'
const pages = import.meta.glob('../pages/**/*.vue', { eager: true })
createInertiaApp({
resolve: (name) => pages[`../pages/${name}.vue`],
setup({ el, App, props, plugin }) {
// Use createSSRApp instead of createApp for hydration
createSSRApp({
render: () => h(App, props),
})
.use(plugin)
.mount(el)
},
})
React:
import { createInertiaApp } from '@inertiajs/react'
import { hydrateRoot } from 'react-dom/client'
const pages = import.meta.glob('../pages/**/*.jsx', { eager: true })
createInertiaApp({
resolve: (name) => pages[`../pages/${name}.jsx`],
setup({ el, App, props }) {
// Use hydrateRoot instead of createRoot for SSR
hydrateRoot(el, <App {...props} />)
},
})
5. Update Layout for SSR Head
Add SSR head injection to your layout:
<!-- app/views/layouts/application.html.erb -->
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1">
<%= csp_meta_tag %>
<%= inertia_ssr_head %>
<%= vite_client_tag %>
<%= vite_javascript_tag 'application' %>
</head>
<body>
<%= yield %>
</body>
</html>
6. Build and Run
# Build both client and SSR bundles
bin/vite build
bin/vite build --ssr
# Start the SSR server
bin/vite ssr
Production Deployment
Process Manager (systemd)
Create /etc/systemd/system/inertia-ssr.service:
[Unit]
Description=Inertia SSR Server
After=network.target
[Service]
Type=simple
User=deploy
WorkingDirectory=/var/www/myapp/current
ExecStart=/usr/bin/node public/vite-ssr/ssr.js
Restart=on-failure
Environment=NODE_ENV=production
[Install]
WantedBy=multi-user.target
sudo systemctl enable inertia-ssr
sudo systemctl start inertia-ssr
Process Manager (PM2)
pm2 start public/vite-ssr/ssr.js --name inertia-ssr
pm2 save
Docker
# Run SSR server alongside Rails
CMD ["sh", "-c", "node public/vite-ssr/ssr.js & bundle exec puma"]
Advanced Configuration
Clustering
For better performance on multi-core systems (requires @inertiajs/core v2.0.7+):
// ssr/ssr.js
createServer(
(page) => createInertiaApp({ /* ... */ }),
{ cluster: true } // Enable clustering
)
This runs multiple Node.js processes on a single port using round-robin request handling.
Custom Port
createServer(
(page) => createInertiaApp({ /* ... */ }),
{ port: 13715 } // Custom port
)
Update Rails config to match:
config.ssr_url = 'http://localhost:13715'
Conditional SSR
Enable SSR only for specific routes:
class ApplicationController < ActionController::Base
# Disable SSR for admin pages
inertia_config(ssr_enabled: false)
end
class PagesController < ApplicationController
# Enable SSR for public pages
inertia_config(ssr_enabled: Rails.env.production?)
end
Title and Meta Tags
Server-Side Meta Tags
Set meta tags in your controller:
class PostsController < ApplicationController
def show
post = Post.find(params[:id])
render inertia: {
post: post.as_json(only: [:id, :title, :content])
}, meta: {
title: post.title,
description: post.excerpt,
og_image: post.cover_image_url
}
end
end
Using Head Component
Vue 3:
<script setup>
import { Head } from '@inertiajs/vue3'
defineProps(['post'])
</script>
<template>
<Head>
<title>{{ post.title }}</title>
<meta name="description" :content="post.excerpt" />
<meta property="og:title" :content="post.title" />
<meta property="og:image" :content="post.coverImageUrl" />
</Head>
<article>
<h1>{{ post.title }}</h1>
<!-- ... -->
</article>
</template>
React:
import { Head } from '@inertiajs/react'
export default function Show({ post }) {
return (
<>
<Head>
<title>{post.title}</title>
<meta name="description" content={post.excerpt} />
<meta property="og:title" content={post.title} />
</Head>
<article>
<h1>{post.title}</h1>
{/* ... */}
</article>
</>
)
}
Default Title Template
createInertiaApp({
title: (title) => title ? `${title} - My App` : 'My App',
// ...
})
Troubleshooting
SSR Server Not Responding
- Check if the SSR server is running:
curl http://localhost:13714 - Check logs:
journalctl -u inertia-ssr -f - Verify the port matches your Rails config
Hydration Mismatch Errors
- Ensure client and server render the same content
- Avoid browser-only APIs in initial render (use
onMounted) - Check for date/time formatting differences
// Bad - different on server vs client
const time = new Date().toLocaleTimeString()
// Good - render after mount
const time = ref(null)
onMounted(() => {
time.value = new Date().toLocaleTimeString()
})
Memory Leaks
- Avoid global state mutations in SSR
- Use request-scoped state only
- Monitor Node.js memory usage
Missing Styles on Initial Load
Ensure CSS is included in the SSR bundle or use critical CSS extraction.
Performance Tips
- Keep SSR lightweight - Defer heavy computations to client
- Use streaming (when supported) for faster TTFB
- Cache SSR responses for static pages
- Monitor SSR latency - Add observability
# Log slow SSR renders
around_action :track_ssr_time, if: -> { request.inertia? }
def track_ssr_time
start = Time.current
yield
duration = Time.current - start
Rails.logger.info "SSR render: #{duration.round(3)}s" if duration > 0.1
end