Skip to main content

Documentation Index

Fetch the complete documentation index at: https://inertiajs.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

You are viewing the documentation for Inertia.js v2. Inertia.js v3 has been released and is now the default version. Please visit the upgrade guide to get started.
Server-side rendering pre-renders your JavaScript pages on the server, allowing your visitors to receive fully rendered HTML when they visit your application. Since fully rendered HTML is served by your application, it’s also easier for search engines to index your site. Server-side rendering uses Node.js to render your pages in a background process; therefore, Node must be available on your server for server-side rendering to function properly.

​
Laravel Starter Kits

If you are using Laravel Starter Kits, Inertia SSR is supported through a build command: 
npm run build:ssr

​
Add Server Entry-Point

To manually configure SSR without a Laravel starter kit, first create an SSR entry point file within your Laravel project. 
touch resources/js/ssr.js
This file is going to look very similar to your app entry point, except it’s not going to run in the browser, but rather in Node.js. Here’s a complete example. 
import { createInertiaApp } from '@inertiajs/vue3'
import createServer from '@inertiajs/vue3/server'
import { renderToString } from 'vue/server-renderer'
import { createSSRApp, h } from 'vue'

createServer(page =>
    createInertiaApp({
        page,
        render: renderToString,
        resolve: name => {
            const pages = import.meta.glob('./Pages/**/*.vue', { eager: true })
            return pages[`./Pages/${name}.vue`]
        },
        setup({ App, props, plugin }) {
            return createSSRApp({
                render: () => h(App, props),
            }).use(plugin)
        },
    }),
)
When creating this file, be sure to add anything that’s missing from your app.js file that makes sense to run in SSR mode, such as plugins or custom mixins.

​
Clustering

By default, the SSR server will run on a single thread. Clustering starts multiple Node servers on the same port, requests are then handled by each thread in a round-robin way. You may enable clustering by passing a second argument of options to createServer. 
import { createInertiaApp } from '@inertiajs/vue3'
import createServer from '@inertiajs/vue3/server'
import { renderToString } from 'vue/server-renderer'
import { createSSRApp, h } from 'vue'

createServer(page =>
    createInertiaApp({
        // ...
    }),
    { cluster: true },
)

​
Client-Side Hydration

import { createApp, h } from 'vue'
import { createSSRApp, h } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'

createInertiaApp({
    resolve: name => {
        const pages = import.meta.glob('./Pages/**/*.vue', { eager: true })
        return pages[`./Pages/${name}.vue`]
    },
    setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) }) 
    createSSRApp({ render: () => h(App, props) }) 
        .use(plugin)
        .mount(el)
    },
})

​
Setup Vite

Next, update your Vite configuration to build the new SSR entry point by adding a ssr property to Laravel’s Vite plugin configuration in your vite.config.js file. 
export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/js/app.js'],
            ssr: 'resources/js/ssr.js', 
            refresh: true,
        }),
        // ...
    ],
})

​
Update NPM Script

Next, update the build script in your package.json file to also build your SSR entry point.
package.json
"scripts": {
    "dev": "vite",
    "build": "vite build"
    "build": "vite build && vite build --ssr"
},
Now you can build both your client-side and server-side bundles. 
npm run build

​
Running the SSR Server

Now that you have built both your client-side and server-side bundles, you should be able run the Node-based Inertia SSR server using the following command. 
php artisan inertia:start-ssr
You may use the --runtime option to specify which runtime you want to use. This allows you to switch from the default Node.js runtime to Bun. 
php artisan inertia:start-ssr --runtime=bun
With the server running, you should be able to access your app within the browser with server-side rendering enabled. In fact, you should be able to disable JavaScript entirely and still navigate around your application.

​
Disabling SSR

Sometimes you may wish to disable server-side rendering for certain pages or routes in your application. You may do so by setting the inertia.ssr.enabled configuration value to false for the current request, typically in a service provider or middleware. 
if (request()->is('admin/*')) {
    config(['inertia.ssr.enabled' => false]);
}

​
Deployment

When deploying your SSR enabled app to production, you’ll need to build both the client-side (app.js) and server-side bundles (ssr.js), and then run the SSR server as a background process, typically using a process monitoring tool such as Supervisor. 
php artisan inertia:start-ssr
To stop the SSR server, for instance when you deploy a new version of your website, you may utilize the inertia:stop-ssr Artisan command. Your process monitor (such as Supervisor) should be responsible for automatically restarting the SSR server after it has stopped. 
php artisan inertia:stop-ssr
You may use the inertia:check-ssr Artisan command to verify that the SSR server is running. This can be helpful after deployment and works well as a Docker health check to ensure the server is responding as expected. 
php artisan inertia:check-ssr
By default, a check is performed to ensure the server-side bundle exists before dispatching a request to the SSR server. In some cases, such as when your app runs on multiple servers or is containerized, the web server may not have access to the SSR bundle. To disable this check, you may set the inertia.ssr.ensure_bundle_exists configuration value to false.

​
Laravel Cloud

To run the SSR server on Laravel Cloud, you may use Cloud’s native support for Inertia SSR.

​
Laravel Forge

To run the SSR server on Forge, you may enable it via the Inertia SSR toggle in your site’s application panel. Forge will create the required daemon and, optionally, update your deploy script to restart the SSR server on each deployment.