TanStack Start SEO: selective SSR, SPA mode and prerendering
TanStack Start SEO explained: what crawlers get under default SSR, selective SSR, SPA mode and prerendering, plus head tags, robots.txt and a curl check.
By Crawlito · 9 min read
In short
- TanStack Start renders the routes matching the initial request on the server by default, so a crawler gets full HTML unless a route or the app opts out.
- A route set to ssr: false or ssr: 'data-only' sends its pendingComponent as the server fallback, or nothing if none is configured, instead of its content.
- A child route can only make the inherited SSR setting more restrictive, so ssr: true under a parent with ssr: false has no effect.
- SPA mode prerenders only the root route into /_shell.html and rewrites requests that would 404 to it, so page text arrives only after JavaScript runs unless you prerender those routes too.
- Titles, canonical links and JSON-LD come from each route's head property and need HeadContent in the root shell to reach the HTML.
On this page
- What crawlers receive from TanStack Start by default
- How selective SSR changes a route's HTML
- What SPA mode ships to crawlers
- How static prerendering fills the gaps
- Titles, canonical links and JSON-LD with the head property
- robots.txt and sitemaps from server routes
- How to check every public route with curl
- Frequently asked questions
- Check one route now
TanStack Start is crawler-friendly by default: the routes that match the first request are rendered on the server, and the HTML that arrives already holds the page text. The risk comes from the opt-outs. A route with ssr: false, a parent route that disables SSR for everything below it, or SPA mode for the whole app can turn a public page back into a shell. Check each public route with a plain HTTP request and look for its own title, text and canonical tag.
This guide is for developers on TanStack Start, including Lovable projects created on or upgraded to it. It covers the four rendering setups the TanStack docs describe, the head tags crawlers read, robots.txt and sitemap routes, and a per-route check. If you are still on a client-rendered React app, start with React SPAs and AI crawlers instead.
What crawlers receive from TanStack Start by default
The Selective SSR guide says that routes matching the initial request are rendered on the server by default. beforeLoad and loader run on the server, the route components render, and the resulting HTML is sent to the client, which then hydrates it. Later navigations run those functions in the browser.
That initial request is the only one a crawler makes. Crawlers request each URL directly, so what matters is the server output for that URL, not what happens on client-side navigation. Many AI crawlers do not run JavaScript: in its December 2024 analysis, Vercel reported that none of the major AI crawlers it measured, including OpenAI's crawlers, ClaudeBot and PerplexityBot, rendered JavaScript at the time. That is why the difference between server and client rendering matters more for them than for Google; SSR, SSG and CSR for AI search explains the background.
The options compare like this:
| Setup | How you set it | What the raw HTML contains |
|---|---|---|
| Default SSR | Nothing, ssr defaults to true | The full rendered route, with loader data |
ssr: 'data-only' | On a route | Loader data runs on the server; the component is not rendered there |
ssr: false | On a route, or defaultSsr: false | The pending fallback, or nothing, in place of the route |
| SPA mode | spa: { enabled: true } in the plugin | One shell with the root route and a pending fallback |
| Static prerendering | prerender: { enabled: true } | Full HTML files written at build time |
How selective SSR changes a route's HTML
Each route takes an ssr property. The docs list three values:
true(default):beforeLoadandloaderrun on the server and the component is rendered to HTML.'data-only':beforeLoadandloaderrun on the server and their results are sent to the client, but the component is rendered only in the browser.false: none of it runs on the server. The loader runs and the component renders on the client during hydration.
You can change the default for the whole app in src/start.ts:
// src/start.ts
import { createStart } from '@tanstack/react-start'
export const startInstance = createStart(() => ({
defaultSsr: false, // every route now opts out unless it says otherwise
}))If you find this line in a project, treat it as a site-wide crawler problem until each public route is checked, because of the inheritance rule below.
The fallback that crawlers see
For the first route in the match that has ssr: false or ssr: 'data-only', the server renders that route's pendingComponent. If it has none, the router's defaultPendingComponent is used. If neither exists, nothing is rendered in its place. So a route that opts out sends whatever your loading state is: often a spinner, sometimes an empty element. That is what a non-rendering crawler indexes.
'data-only' is easy to misread as safe for SEO. The data is fetched on the server, but the component that turns it into headings and paragraphs is not rendered there, so the page text is still missing from the HTML.
The inheritance rule
The docs say a child route inherits its parent's SSR setting, and can only change it to something more restrictive: true to 'data-only' or false, and 'data-only' to false. A child cannot switch SSR back on.
root { ssr: undefined } -> true
posts { ssr: false } -> false
$postId { ssr: true } -> still false: true is ignoredIn practice: if a layout route sets ssr: false, perhaps because a sidebar uses localStorage, every page under that layout loses server rendering, whatever the pages themselves say. Fix it at the layout. Move browser-only code into effects or a client-only component, and keep public content routes on the default.
Choosing per request
The ssr property can also be a function that receives params and search after validation and returns true, false or 'data-only'. It runs only on the server for the initial request and is stripped from the client bundle. The docs' example uses it to skip server rendering for one document type and to switch to 'data-only' when a search parameter is set. Make sure the function never returns false for public URLs a crawler might request.
Disabling SSR for the root route
If the root route sets ssr: false, the <html> shell still has to come from the server. The docs handle this with shellComponent, which is always rendered on the server and wraps the root component, error component and not-found component. The shell is where <HeadContent /> and <Scripts /> live, but with root SSR off, the content inside it is rendered in the browser.
What SPA mode ships to crawlers
The SPA mode guide is direct about the trade-off. It lists "Less SEO friendly" as a caveat and says the initial document does not contain the rendered HTML of your application until JavaScript renders it on the client.
When SPA mode is on, the build adds a prerendering step that:
- Prerenders only the root route.
- Renders the router's pending fallback where matched routes would go.
- Saves the result as
/_shell.htmlby default. - Configures default rewrites so that requests that would otherwise 404 get the shell.
The same guide says deployments usually need host redirects for this, and its Netlify example is a catch-all /* /_shell.html 200 rule placed after any rules for server functions and server routes.
// vite.config.ts
export default defineConfig({
plugins: [
tanstackStart({
spa: { enabled: true },
}),
],
})Every URL without its own file therefore returns the same HTML, with the same head tags and no route content. The docs suggest the shell for "generic head tags for SPA routes", which is fine for an app behind a login and wrong for pricing or blog pages. Loaders on the root route do run while the shell is prerendered, so anything the root renders from them is in the shell, but that is shared by every URL.
Two consequences follow. A crawler cannot tell your pages apart, and a URL that does not exist returns the shell with a 200 from the rewrite rule, as covered in SPA 404 status codes. The SPA guide itself recommends prerendering as many routes as you can in SPA mode, which leads to the next option.
How static prerendering fills the gaps
The Static Prerendering guide writes HTML files at build time. You enable it in the plugin options:
// vite.config.ts
tanstackStart({
prerender: {
enabled: true,
crawlLinks: true, // follow links in rendered pages and prerender them too
filter: ({ path }) => !path.startsWith('/app'),
},
pages: [{ path: '/products/example-item' }], // a path discovery would miss
})Some rules from the docs decide which pages you get:
- With
autoStaticPathsDiscoveryon (the default), static routes are found automatically and merged with thepageslist. - Routes with path parameters such as
/posts/$postId, layout routes prefixed with_, and routes without components are excluded from discovery. - Dynamic routes can still be prerendered if a prerendered page links to them and
crawlLinksis on.
So a blog that links every post from an index page is covered by crawlLinks. A product catalogue whose pages are reachable only through search is not, and needs those paths listed in pages or server rendering. Inside the SPA mode prerender options, crawlLinks defaults to false, so turn it on there if you want linked pages prerendered.
Titles, canonical links and JSON-LD with the head property
The router's document head management guide says each route's head property returns meta, links, styles and scripts, and that rendering <HeadContent /> and <Scripts /> is required. Titles and meta tags are deduplicated, and the last occurrence in the nested routes wins, so a post's title replaces the root's.
The Start SEO guide shows one route handling all three crawler-facing tags:
// src/routes/posts/$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
loader: async ({ params }) => ({ post: await fetchPost(params.postId) }),
head: ({ loaderData, params }) => ({
meta: [
{ title: loaderData.post.title },
{ name: 'description', content: loaderData.post.excerpt },
],
links: [
{ rel: 'canonical', href: `https://www.example.com/posts/${params.postId}` },
],
scripts: [
{
type: 'application/ld+json',
children: JSON.stringify({
'@context': 'https://schema.org',
'@type': 'Article',
headline: loaderData.post.title,
datePublished: loaderData.post.publishedAt,
}),
},
],
}),
component: PostPage,
})Here head reads loaderData. On a route with ssr: false, the docs say the loader runs on the client, so do not assume those tags are in the server HTML: check them. Write canonical URLs with your real production host, and keep JSON-LD to facts visible on the page. The SEO guide suggests the Google Rich Results Test to validate it.
robots.txt and sitemaps from server routes
The SEO guide shows a static file and a server route for both files, plus a built-in sitemap option covered below. The simple one is a static file in public/, served at /robots.txt or /sitemap.xml. For rules that differ per environment, or a sitemap of content that cannot be discovered at build time, use a server route. The [.] in the file name escapes the dot:
// src/routes/robots[.]txt.ts
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/robots.txt')({
server: {
handlers: {
GET: async () =>
new Response(
process.env.DEPLOY_ENV === 'production'
? 'User-agent: *\nAllow: /\n\nSitemap: https://www.example.com/sitemap.xml\n'
: 'User-agent: *\nDisallow: /\n',
{ headers: { 'Content-Type': 'text/plain' } },
),
},
},
})DEPLOY_ENV here is your own variable, not a TanStack setting. The environment check is the point of a dynamic route: it stops a staging Disallow: / from reaching production. A sitemap route works the same way with Content-Type: application/xml. The guide also documents a build-time sitemap, sitemap: { enabled: true, host: 'https://www.example.com' }, generated from pages discovered while prerendering with crawlLinks.
In SPA mode, the guide says server routes need their own redirect rules ahead of the catch-all shell rule, otherwise /robots.txt can be answered with the shell. A static file in public/ avoids that, since the guide notes most CDNs serve existing static files first by default.
How to check every public route with curl
Fetch each route without a browser and confirm four things: its own title, a canonical tag, a sentence from the page and, where relevant, JSON-LD.
for route in / /pricing /blog /posts/first-post; do
html=$(curl -s "https://www.example.com$route")
echo "== $route"
echo "$html" | grep -o '<title>[^<]*</title>'
echo "$html" | grep -o '<link[^>]*rel="canonical"[^>]*>'
echo "$html" | grep -c 'application/ld+json'
done
# replace the phrase with a sentence that appears on your page
curl -s https://www.example.com/pricing | grep -c "Cancel any time"How to read the results:
| What you see | Likely cause | Fix |
|---|---|---|
| Same title on every route | SPA mode, or head only on the root | Prerender or server-render those routes; add head per route |
| Your spinner markup and no text | ssr: false or 'data-only' on the route or a parent | Find the first opted-out route in the tree and remove the opt-out |
| Title present, text missing | Content fetched in an effect, not the loader | Move the fetch into loader; see TanStack Query and SWR hydration |
Shell HTML with a 200 for made-up URLs | SPA mode catch-all shell rewrite | Return a real 404 for unknown paths |
Add -A with a crawler user agent to check rules keyed on it, and remember that a copied user agent does not reproduce firewall checks on the crawler's IP. See your page as an AI crawler with curl has a word-count script. For Lovable projects, Lovable's upgrade guide warns that some browser-only libraries can break server rendering and that its checks may not catch every case, so rerun this loop after the upgrade and after any fix that moves code to the browser. Lovable, Bolt and v0 SEO covers the pre-upgrade setup.
Frequently asked questions
Is TanStack Start good for SEO?
Its default is server rendering of the first request, which gives crawlers full HTML. The outcome depends on your configuration, so check that no public route or parent layout opts out of SSR.
Can a child route turn SSR back on?
No. The docs say a child can only make the inherited setting more restrictive, so ssr: true under a parent with ssr: false is ignored.
Is ssr: 'data-only' enough for crawlers?
No. The loader runs on the server, but the component is rendered in the browser, so the server HTML holds the pending fallback instead of the page text.
Should I use SPA mode for a marketing site?
Not for pages you want found. SPA mode serves one shell for every URL; use default SSR or static prerendering for public pages and keep SPA mode, or ssr: false, for logged-in screens.
Will server rendering get my TanStack Start site into AI answers?
No one can promise that. Rendered HTML removes a technical barrier so crawlers can read the page; whether an assistant uses or cites it depends on many other factors.
Check one route now
Pick the public page that matters most and run the curl loop above on it. To see how much of its text reaches an AI crawler in the raw HTML without setting anything up, run the free check, no account needed.
Filed under Platform guides. Topics: react, ssr, rendering, javascript, raw-html