Server-side Rendering (SSR)

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.

Laravel starter kits

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

npm run build:ssr

Install dependencies

If you are not using a Laravel starter kit and would like to manually configure SSR, we'll first install the additional dependencies required for server-side rendering. This is only necessary for the Vue adapters, so you can skip this step if you're using React or Svelte.

npm install @vue/server-renderer

Add server entry-point

Next, we'll create a resources/js/ssr.js file within our Laravel project that will serve as our SSR entry point.

touch resources/js/ssr.js

This file is going to look very similar to your resources/js/app.js file, 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 can 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 },
)

Setup Vite

Next, we need to update our Vite configuration to build our new ssr.js file. We can do this by adding a ssr property to Laravel's Vite plugin configuration in our vite.config.js file.

export default defineConfig({
  plugins: [
    laravel({
      input: ['resources/css/app.css', 'resources/js/app.js'],
+     ssr: 'resources/js/ssr.js',
      refresh: true,
    }),
    // ...
  ],
})

Update npm script

Next, let's update the build script in our package.json file to also build our new ssr.js file.

  "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.

Client side hydration

Since your website is now being server-side rendered, you can instruct Vue to "hydrate" the static markup and make it interactive instead of re-rendering all the HTML that we just generated.

To enable client-side hydration in a Vue app, update your ssr.js file to use createSSRApp instead of createApp.

- 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)
    },
  })

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 should create a new daemon that runs php artisan inertia:start-ssr from the root of your app. Or, you may utilize the built-in Inertia integration from your Forge application's management dashboard.

Next, whenever you deploy your application, you can automatically restart the SSR server by calling the php artisan inertia:stop-ssr command. This will stop the existing SSR server, forcing a new one to be started by your process monitor.

Heroku

To run the SSR server on Heroku, update the web configuration in your Procfile to run the SSR server before starting your web server.

web: php artisan inertia:start-ssr & vendor/bin/heroku-php-apache2 public/

Note, you must have the heroku/nodejs buildpack installed in addition to the heroku/php buildback for the SSR server to run.