Laravel Inertia SEO: turn on SSR so crawlers get real HTML
Laravel Inertia SEO starts with SSR: without it, crawlers get an empty root element and a JSON page object. How to build, run and verify Inertia SSR.
By Crawlito · 8 min read
In short
- Without server-side rendering, an Inertia page's first HTML response holds an empty root div and the page object as JSON, so crawlers that do not run JavaScript find no visible text.
- Inertia 3 always puts the page object in a script element of type application/json; Inertia 2 used a data-page attribute on the root div unless you opted in to the script element.
- Setting ssr.enabled to true in config/inertia.php is not enough: in production you also need the SSR bundle (vite build --ssr) and a running php artisan inertia:start-ssr process.
- If the SSR server is down, Inertia falls back to client-side rendering without an error page, so a broken setup can go unnoticed.
- Titles and meta tags set with the Head component only reach the first HTML response when SSR is working.
On this page
- What an Inertia page sends a crawler without SSR
- Why Laravel's starter kits are not server-rendered out of the box
- How to set up Inertia SSR
- Titles and meta tags with the Head component
- Running the SSR server in production
- How to check that SSR is working
- robots.txt, Blade and Livewire pages
- Frequently asked questions
- Check what crawlers receive
A Laravel app that uses Inertia with React or Vue renders on the client until you set up server-side rendering. The first HTML response for every URL contains an empty root element and the page's props as JSON, so a crawler that does not run JavaScript gets data but no readable page. Inertia's documented fix is server-side rendering (SSR): build an SSR bundle, run Inertia's Node SSR server next to Laravel, and the same response then carries the rendered HTML, title and meta tags.
This post is the Laravel-specific version of a general problem. If you want the background on why empty HTML matters for AI crawlers, read the empty HTML problem first. Here we cover what an Inertia response looks like, the SSR setup from the Inertia and Laravel docs, running it in production, and how to check it worked.
What an Inertia page sends a crawler without SSR
Inertia's protocol page describes two kinds of response for the same URL. The first visit is a normal request with no Inertia headers, and the server returns a full HTML document. After the app has loaded, the client sends X-Inertia: true on each navigation and gets the page object back as JSON, with Vary: X-Inertia so caches keep the two apart. Crawlers never send that header, so they always get the HTML document.
In Inertia 3 that document's body looks like this:
<script data-page="app" type="application/json">{"component":"Pricing","props":{"errors":{},"plans":[{"name":"Team"}]},"url":"\/pricing","version":"6b16b94d7c51cbe5b1fa42aac98241d5"}</script>
<div id="app"></div>The page object carries component, props, url and version, plus optional fields such as encryptHistory. The Laravel adapter escapes forward slashes and < characters so the JSON cannot close the script element early, which is why the URL reads \/pricing. Inertia 2 put the same JSON in a data-page attribute on the root <div id="app"> unless you enabled its useScriptElementForInitialPage option; Inertia 3's upgrade guide says the attribute is no longer supported.
Either way, the result for a non-rendering crawler is the same:
- The
<div id="app">is empty. Headings, paragraphs and links only exist after React or Vue runs. - Your content may be in the JSON, but as data inside a script element, not as text on a page. Do not count on a crawler to read your props and work out what the page says.
- The
<title>is whatever your Blade root template prints, usually the app name, on every URL.
One side effect worth knowing: everything you pass as props is in the HTML source of the first response, SSR or not. Keep anything you would not publish out of the props.
Why Laravel's starter kits are not server-rendered out of the box
Laravel's starter kits page says the React, Svelte and Vue kits are built with Inertia 3 and are "compatible with" Inertia's server-side rendering. Compatible is not the same as switched on. At the time of writing, the kits' package.json files on GitHub define two build scripts, and only the second builds the SSR bundle:
{
"scripts": {
"build": "vp build",
"build:ssr": "vp build && vp build --ssr"
}
}The kits currently call Vite through Vite+ (vp); in a project that calls Vite directly, the same pair is vite build and vite build --ssr. If your deploy runs npm run build, you ship a client-only app. Laravel's docs tell you to run npm run build:ssr instead, and they also describe a composer dev:ssr command for testing SSR locally; check that your kit's composer.json still defines it before relying on it.
The configuration can mislead you. The published config/inertia.php in the adapter has ssr.enabled set to true by default, through INERTIA_SSR_ENABLED. The comment above it in the inertia-laravel config is plain about the limit: enabling these options will not make SSR work on its own, because a separate rendering service has to be available. With ensure_bundle_exists also true by default, Laravel checks for the SSR bundle before sending a render request, and without one it serves the client-side shell.
| What you have | What a crawler gets |
|---|---|
ssr.enabled true, no SSR bundle built (production) | Empty root div and JSON |
| SSR bundle built, SSR server not running | Empty root div and JSON (fallback) |
| SSR bundle built and server running | Rendered HTML inside the root, plus head tags |
ssr.enabled false, or route listed in $withoutSsr | Empty root div and JSON |
How to set up Inertia SSR
The steps below follow Inertia's server-side rendering guide at the time of writing. The SSR server needs Node.js 22 or higher.
1. Add the Inertia Vite plugin
The recommended path is the @inertiajs/vite plugin next to Laravel's own Vite plugin. It detects your SSR entry point, and by default it reuses app.js for SSR, so you do not need a separate file.
// vite.config.js
import inertia from '@inertiajs/vite'
import laravel from 'laravel-vite-plugin'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [
laravel({
input: ['resources/js/app.js'],
refresh: true,
}),
inertia(),
],
})If you need more control, you can write a separate resources/js/ssr.js (or ssr.jsx for React) entry with createServer from @inertiajs/react/server or @inertiajs/vue3/server. To manage the SSR build entirely yourself, the docs show passing that file to the Laravel plugin's ssr option and setting inertia({ ssr: false }).
2. Hydrate if you wrote your own setup callback
With the Vite plugin and a minimal createInertiaApp() call, the plugin handles mounting and SSR for you. If your app.js has a manual setup callback, the client-side setup docs say the plugin no longer generates SSR handling: you need a separate SSR entry point, and the client has to attach to the server markup instead of replacing it. In React that means hydrateRoot instead of createRoot:
import { createInertiaApp } from '@inertiajs/react'
import { hydrateRoot } from 'react-dom/client'
createInertiaApp({
resolve: name => {
const pages = import.meta.glob('./Pages/**/*.jsx')
return pages[`./Pages/${name}.jsx`]()
},
setup({ el, App, props }) {
hydrateRoot(el, <App {...props} />)
},
})In Vue, use createSSRApp instead of createApp. If the server and client markup differ, you get hydration errors; React hydration errors and crawlers explains why that matters even when the page looks fine.
3. Build both bundles
{
"scripts": {
"dev": "vite",
"build": "vite build && vite build --ssr"
}
}In development, npm run dev is enough: the docs say the plugin exposes a render endpoint for Laravel, so there is no SSR bundle to build and no separate Node process to start.
4. Keep the head tags in the root template
Inertia's title and meta page recommends the Blade components <x-inertia::head> and <x-inertia::app /> in resources/views/app.blade.php. The fallback inside <x-inertia::head> is printed only when SSR is not active. With SSR active, the <Head> component on each page supplies the tags instead.
<head>
@vite('resources/js/app.js')
<x-inertia::head>
<title>{{ config('app.name') }}</title>
<meta name="description" content="My application description">
</x-inertia::head>
</head>
<body>
<x-inertia::app />
</body>The older @inertiaHead and @inertia directives still work, but the setup docs say they do not offer the SSR head fallback.
Titles and meta tags with the Head component
Set a title and description on each page with Head from @inertiajs/react or @inertiajs/vue3. Use head-key so a page's tag replaces the layout's default instead of adding a second one:
import { Head } from '@inertiajs/react'
export default function Pricing() {
return (
<>
<Head title="Pricing">
<meta head-key="description" name="description" content="Plans for teams of 1 to 50." />
<link head-key="canonical" rel="canonical" href="https://example.com/pricing" />
</Head>
<h1>Pricing</h1>
</>
)
}A title callback in createInertiaApp formats every title, for example title: (title) => \${title} - My App``. All of this only reaches the first HTML response when SSR works. Without SSR, the browser updates the title after load and crawlers that do not run JavaScript keep the Blade fallback. Page titles and meta descriptions covers what to put in them.
For links, Inertia's <Link> renders a real <a> element by default, which crawlers can follow. Links with method="post" and similar render as <button>, which is what you want for actions like logging out.
Running the SSR server in production
The production sequence in the Inertia docs is short:
npm run build
php artisan inertia:start-ssrThe SSR server is a long-running Node process, so run it under a process monitor that restarts it. The docs name Supervisor; a minimal program block might look like this (adjust the paths and user):
[program:inertia-ssr]
command=php /var/www/app/artisan inertia:start-ssr
directory=/var/www/app
user=www-data
autostart=true
autorestart=true
stopwaitsecs=10Other documented options at the time of writing:
- Laravel Forge has an Inertia SSR toggle in the site's application panel that creates the daemon and can restart SSR on each deploy.
- Laravel Cloud supports Inertia SSR natively.
- Restart on deploy. The docs say to run
php artisan inertia:stop-ssrwhen you deploy a new version and let the process monitor start the server again. From adapter v3.4.0,--gracefulmakes the command succeed when no SSR server is running yet. - Multiple servers or containers. Set
ensure_bundle_existsto false when the bundle is not on the same filesystem as Laravel. - Clustering. The SSR server runs on a single thread by default;
cluster: trueruns several Node workers on one port.
You can also exclude routes. The $withoutSsr array on HandleInertiaRequests (for example 'admin/*') or Inertia::withoutSsr() keeps logged-in screens client-side while public pages are rendered on the server.
How to check that SSR is working
Inertia falls back to client-side rendering when SSR fails, and its docs warn that failures "may go unnoticed". Users still see a working site, so check the raw HTML on purpose:
- Health check.
php artisan inertia:check-ssrverifies that the SSR server responds. Add it to your monitoring. - Text in the root. Fetch a public page without a browser and look for a heading you expect:
curl -s https://example.com/pricing | grep -c "<h1"
curl -s https://example.com/pricing | grep -o '<div id="app"></div>'The first command should return at least 1. The second should print nothing: an empty <div id="app"></div> means the fallback was served.
- Per-page head. Check that each URL returns its own
<title>, description and canonical tag in the raw response, not the Blade fallback. - Failures in logs. Listen for the
Inertia\Ssr\SsrRenderFailedevent and report it, so a crashed SSR process shows up before crawlers notice.
How to see your page as an AI crawler, with curl adds crawler user agents and a word-count script for a fuller comparison.
robots.txt, Blade and Livewire pages
A fresh Laravel app ships public/robots.txt with User-agent: * and an empty Disallow:, which allows every crawler. Your web server serves it as a static file, so edit it there; it does not go through Inertia at all. robots.txt for AI crawlers covers which groups to add.
Not every page in a Laravel app needs Inertia SSR. Routes that return a Blade view, and Livewire pages, are rendered by PHP before the response leaves the server, so their text is normally already in the raw HTML. A common pattern is Blade for the marketing site and blog, and Inertia for the logged-in app. Verify with the same curl check rather than assuming, since a Blade page can still load its main content with JavaScript.
Frequently asked questions
Does Google index Inertia pages without SSR?
Google Search runs JavaScript in an evergreen Chromium, so it can usually see client-rendered Inertia pages after rendering. AI crawler operators do not document JavaScript rendering, so SSR is what makes the same text reliably visible to them; do AI crawlers run JavaScript? has the details.
Is the JSON page object enough for crawlers?
Do not rely on it. It is data inside a script element, not page text, and how each crawler treats it is not documented.
Do I need a separate ssr.js file in Inertia 3?
Not with the @inertiajs/vite plugin, which reuses app.js for SSR by default. Write a separate entry only when you need a custom setup.
What happens if the SSR server crashes?
Inertia serves the client-side shell instead, so users see no error but crawlers get an empty root again. Monitor inertia:check-ssr and the SsrRenderFailed event.
Will turning on SSR get my Laravel app cited in AI answers?
No one can promise that. SSR removes a technical barrier so crawlers can read your pages; whether an assistant cites them depends on many things outside your site.
Check what crawlers receive
After deploying SSR, run the free check on a public Inertia page to see whether its main text and title are in the raw HTML. If you want every public route checked, including the ones that silently fell back to client-side rendering, an audit compares raw and rendered HTML across up to 500 pages.
Filed under Platform guides. Topics: laravel, ssr, react, vue, javascript, raw-html