Skip to content

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

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:

SetupHow you set itWhat the raw HTML contains
Default SSRNothing, ssr defaults to trueThe full rendered route, with loader data
ssr: 'data-only'On a routeLoader data runs on the server; the component is not rendered there
ssr: falseOn a route, or defaultSsr: falseThe pending fallback, or nothing, in place of the route
SPA modespa: { enabled: true } in the pluginOne shell with the root route and a pending fallback
Static prerenderingprerender: { 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): beforeLoad and loader run on the server and the component is rendered to HTML.
  • 'data-only': beforeLoad and loader run 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:

tsx
// 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 ignored

In 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:

  1. Prerenders only the root route.
  2. Renders the router's pending fallback where matched routes would go.
  3. Saves the result as /_shell.html by default.
  4. 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.

ts
// 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:

ts
// 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 autoStaticPathsDiscovery on (the default), static routes are found automatically and merged with the pages list.
  • 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 crawlLinks is 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.

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:

tsx
// 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:

ts
// 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.

bash
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 seeLikely causeFix
Same title on every routeSPA mode, or head only on the rootPrerender or server-render those routes; add head per route
Your spinner markup and no textssr: false or 'data-only' on the route or a parentFind the first opted-out route in the tree and remove the opt-out
Title present, text missingContent fetched in an effect, not the loaderMove the fetch into loader; see TanStack Query and SWR hydration
Shell HTML with a 200 for made-up URLsSPA mode catch-all shell rewriteReturn 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