TanStack Start SEO: Practical Guide (2026)

TanStack Start SEO guide: implement route metadata, canonicals, sitemaps, structured data, SSR checks, and Core Web Vitals.

Huifer
Huifer
September 18, 20268 min read
Also available in:Deutsch · 中文

Written by Huifer, solo developer and maintainer of TanStack Ship. I have built and maintained production applications on TanStack Start and I have run the SEO checks below against my own deployed routes — inspecting the raw HTTP response, comparing View Source with the hydrated DOM, and checking Search Console for the indexed version. The failures I found were not exotic: a generic title on a dynamic route, a canonical built from the incoming Host header, a sitemap that still listed a retired slug, and alternates pointing at locale pages that 404'd. This guide focuses on implementation details you can inspect and verify in your own TanStack Start application. Rendering, metadata, indexing, and performance depend on your route configuration, content, deployment, and Google's processing; no framework guarantees rankings.

Official references: TanStack Start SEO · Google JavaScript SEO basics · Google structured data · Core Web Vitals Last updated: 2026-10-25 · Changelog

TanStack Start SEO: Practical Guide

Direct answer: TanStack Start SEO is the work of making each public route discoverable and understandable to search engines: return useful HTML, set route-specific titles and descriptions, choose a canonical URL, expose crawlable URLs and language variants, and add accurate structured data where it fits. TanStack Start provides server rendering and route head management, but your configuration and content determine what is published.

Executive summary: Use the route head option for unique metadata and canonical/alternate links. Publish a sitemap containing only canonical, indexable URLs and a robots.txt that points to it. Add JSON-LD only when it matches visible page content. Verify the raw HTTP response as well as the hydrated browser page, then use Search Console and field performance data to find issues. SSR helps deliver HTML; it does not guarantee indexing, rich results, or rankings.

1. Per-route metadata and canonical URLs

In current TanStack Start / Router documentation, route head information is declared with head; the root document must render <HeadContent /> inside <head>. Use loader data for page-specific titles and descriptions, and set a production canonical from a known site origin rather than trusting an arbitrary incoming Host header. The canonical should be an absolute URL, use the preferred protocol/host/path, and exclude tracking parameters. Do not canonicalize distinct pages to one URL just to consolidate them.

tsx
// src/routes/articles/$slug.tsx
import { createFileRoute } from '@tanstack/react-router'

type Article = {
  slug: string
  title: string
  description: string
  excerpt: string
  updatedAt: string
}

const SITE_ORIGIN = 'https://www.example.com'

async function getArticle(slug: string): Promise<Article> {
  const response = await fetch(
    `${SITE_ORIGIN}/api/public/articles/${encodeURIComponent(slug)}`,
  )
  if (!response.ok) throw new Error(`Article request failed: ${response.status}`)
  return response.json() as Promise<Article>
}

export const Route = createFileRoute('/articles/$slug')({
  loader: ({ params }) => getArticle(params.slug),
  head: ({ loaderData }) => {
    const article = loaderData
    const canonical = new URL(
      `/articles/${encodeURIComponent(article.slug)}`,
      SITE_ORIGIN,
    ).href

    return {
      meta: [
        { title: `${article.title} | Example` },
        { name: 'description', content: article.description },
        { property: 'og:title', content: article.title },
        { property: 'og:description', content: article.description },
        { property: 'og:url', content: canonical },
      ],
      links: [{ rel: 'canonical', href: canonical }],
    }
  },
  component: ArticlePage,
})

function ArticlePage() {
  const article = Route.useLoaderData()
  return <article><h1>{article.title}</h1><p>{article.excerpt}</p></article>
}

The API endpoint and ArticlePage above are application-owned; implement them with your public content source and render the substantive article body. Keep titles and descriptions concise and specific, not a list of keywords. A canonical is a hint to search engines, not an access-control mechanism. TanStack's document head management guide explains route head merging; Google's canonical URL guidance describes how canonical signals are handled.

2. Hreflang for English, Chinese, and German

Use hreflang only when you have equivalent pages available in multiple languages. Each localized page should identify itself and its alternate equivalents, with reciprocal links and valid absolute URLs. Use language tags such as en, zh, and de; select a canonical within each language version rather than pointing all translations at English. An x-default alternate is optional when there is a suitable language selector or fallback page.

tsx
const SITE_ORIGIN = 'https://www.example.com'

function languageAlternates(slug: string) {
  const encodedSlug = encodeURIComponent(slug)
  return [
    { lang: 'en', path: `/en/articles/${encodedSlug}` },
    { lang: 'zh', path: `/zh/articles/${encodedSlug}` },
    { lang: 'de', path: `/de/articles/${encodedSlug}` },
  ].map(({ lang, path }) => ({
    rel: 'alternate' as const,
    hrefLang: lang,
    href: new URL(path, SITE_ORIGIN).href,
  }))
}

// In each localized route's head():
const links = [
  { rel: 'canonical' as const, href: new URL(currentPath, SITE_ORIGIN).href },
  ...languageAlternates(article.translationGroupSlug),
]

Replace translationGroupSlug with an identifier that maps to the actual translated routes; do not emit a language URL that returns an error or unrelated content. TanStack Router's links head entries support hrefLang. Follow Google's localized-version guidance and test all language variants together.

3. Sitemap and robots.txt

TanStack Start does not automatically know which URLs in your content system are public, canonical, and indexable. Generate the sitemap from that source of truth. Exclude drafts, redirects, noindex pages, and duplicate parameterized URLs. Use real modification dates only when they represent meaningful page changes; sitemap fields such as priority and change frequency are not a substitute for URL discovery.

ts
// src/routes/sitemap[.]xml.ts
import { createFileRoute } from '@tanstack/react-router'

const SITE_ORIGIN = 'https://www.example.com'
const staticPaths = ['/', '/pricing', '/blog']
const publishedSlugs = ['tanstack-start-seo', 'routing-guide'] // Replace with published CMS records.

function escapeXml(value: string) {
  return value.replace(/[<>&'\"]/g, (char) => ({
    '<': '&lt;', '>': '&gt;', '&': '&amp;', "'": '&apos;', '"': '&quot;',
  })[char]!)
}

export const Route = createFileRoute('/sitemap[.]xml')({
  server: {
    handlers: {
      GET: async () => {
        const paths = [
          ...staticPaths,
          ...publishedSlugs.map((slug) => `/blog/${encodeURIComponent(slug)}`),
        ]
        const urls = paths.map((path) => {
          const loc = escapeXml(new URL(path, SITE_ORIGIN).href)
          return `<url><loc>${loc}</loc></url>`
        }).join('')
        const xml = `<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls}</urlset>`
        return new Response(xml, {
          headers: { 'Content-Type': 'application/xml; charset=utf-8' },
        })
      },
    },
  },
})

Expose a robots route separately, as plain text, and reference the sitemap's canonical public URL:

ts
// src/routes/robots[.]txt.ts
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/robots[.]txt')({
  server: {
    handlers: {
      GET: async () => new Response(
        'User-agent: *\\nAllow: /\\nSitemap: https://www.example.com/sitemap.xml\\n',
        { headers: { 'Content-Type': 'text/plain; charset=utf-8' } },
      ),
    },
  },
})

Replace the illustrative slug array with published records and split large sites into sitemap indexes as needed. Robots rules control crawling, not access permissions or guaranteed de-indexing. Ensure important pages remain crawlable and don't accidentally disallow assets needed for rendering. See Google's sitemap documentation and robots.txt guidance.

4. JSON-LD that matches the page

Structured data describes visible content; it is not a ranking guarantee. Choose a supported schema type that actually describes the page, use factual values from the page's data, and do not add invented ratings, prices, authors, or reviews. Validate syntax and eligibility with Google's Rich Results Test, then inspect Search Console for enhancement issues.

tsx
head: ({ loaderData }) => {
  const article = loaderData
  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'Article',
    headline: article.title,
    description: article.description,
    dateModified: article.updatedAt,
    mainEntityOfPage: new URL(
      `/articles/${encodeURIComponent(article.slug)}`,
      'https://www.example.com',
    ).href,
  }

  return {
    meta: [{ title: `${article.title} | Example` }],
    scripts: [{
      type: 'application/ld+json',
      // Escape '<' to prevent content from ending the script element.
      children: JSON.stringify(jsonLd).replace(/</g, '\\u003c'),
    }],
  }
}

Add other Article fields only when the page and its visible content support them. TanStack Start exposes route head scripts; consult its SEO guide and Google's structured data introduction.

5. Verify SSR and the delivered HTML

Do not assume a route is search-ready because it works after client-side navigation. Check the actual HTTP response for a direct request to each important URL. The response should have the intended status, meaningful page content, a unique title and description, canonical, and any intended alternate or JSON-LD tags.

sh
# Inspect status/headers and the initial HTML returned by the deployed server.
curl -sS -D /tmp/seo-headers.txt \
  -o /tmp/seo-page.html \
  https://www.example.com/articles/example-slug
head -n 20 /tmp/seo-headers.txt
grep -Eo '<title>[^<]*</title>|<meta[^>]+name="description"[^>]*>|<link[^>]+canonical[^>]*>|application/ld\+json' \
  /tmp/seo-page.html

Use an article URL that exists in your deployment. The shell command reports only what the server returned; it does not prove Google has crawled or indexed it. In a browser, compare View Source (initial response) with the live DOM in DevTools after hydration. Check for duplicate head tags, hydration errors, missing content, and client-side changes to canonical or metadata. Then use Search Console's URL Inspection for the indexed version and, when appropriate, its live test. The live test is a diagnostic, not a promise that Google will index the page. For client-rendered or dynamic pages, Google's JavaScript SEO documentation explains its rendering process.

6. Core Web Vitals and page experience

Measure rather than infer performance from the framework choice. Current “good” Core Web Vitals thresholds, evaluated at the 75th percentile, are LCP at or below 2.5 seconds, INP at or below 200 milliseconds, and CLS at or below 0.1. SSR can make meaningful content available in the initial document, but it does not by itself fix slow server responses, oversized images, blocking scripts, layout shifts, or expensive client interactions.

Start with real-user field data in Search Console and PageSpeed Insights, then use browser performance tools or Lighthouse to investigate reproducible causes. Optimize the actual LCP resource, reserve image and embed dimensions to prevent layout shifts, and reduce long main-thread work for interaction responsiveness. A preload or high fetch priority is useful only when it targets the real critical resource and does not compete with more important work. See web.dev's Core Web Vitals and Google Search Central's page experience guidance.

What I verify before calling a TanStack Start page SEO-ready

When I review a route, I do not stop at “the page renders in the app.” I open the deployed URL directly, save the initial HTML, and compare it with the hydrated DOM. The process is deliberately boring because it catches the failures that a local client-side navigation hides.

Before: a route can look complete after hydration while its direct response has a generic title, no canonical, or an empty content shell. After: the route is treated as ready only when the initial response, View Source, live DOM, sitemap entry, and Search Console inspection agree on the public URL and page identity. Verification: I record the URL, HTTP status, title, canonical, alternates, and inspection date in the release checklist; this is a validation procedure, not a ranking result.

The edge cases I check first are:

  • Dynamic parameters: the loader must return a real article or a 404; a generic fallback page should not be emitted for every unknown slug.
  • Locale prefixes: /en/, /zh/, and /de/ need real equivalent content before they are emitted as alternates.
  • Duplicate URLs: trailing slashes, tracking parameters, preview routes, and old slugs must resolve consistently or be excluded from the sitemap.
  • Client-only pages: private dashboards and login-gated screens normally do not belong in the public SEO surface; adding metadata does not make them useful to crawlers.
  • JSON-LD parity: structured data must describe visible content. Do not add review scores, prices, or authors that the page does not show.

A useful release check is therefore a set of observations, not a promise: HTTP status, initial HTML, title, description, canonical, hreflang, sitemap membership, JSON-LD validity, and field/lab performance evidence.

Limitations and validation checklist

TanStack Start gives you SSR and route-level head APIs; it cannot ensure that the server returns the right status and content for every URL, that a sitemap stays synchronized with a CMS, that Google chooses your canonical, or that a page is indexed, earns a rich result, or ranks. Search engines may select different snippets, ignore structured data, or take time to process updates. robots.txt is not a privacy boundary. Core Web Vitals vary by device, network, and field sample. Verify the deployed output and keep the evidence dated rather than presenting an untested configuration as a result.

  • Each indexable route returns the intended HTTP status and useful initial HTML on a direct request.
  • Each route has a specific title and description, and <HeadContent /> is in the root document.
  • Canonical URLs are absolute, stable, and match the intended public URL.
  • English, Chinese, and German alternates are reciprocal and point to real equivalent pages.
  • Sitemap contains only canonical public URLs; robots.txt references it without blocking needed pages.
  • JSON-LD validates and accurately reflects visible page content.
  • curl response, browser View Source/live DOM, and Search Console URL Inspection have been checked; findings are recorded as observed, not assumed.
  • Field Core Web Vitals and lab diagnostics are reviewed separately, with fixes based on measured bottlenecks.

Related reading: TanStack Query v5 guide · TanStack Query best practices · TanStack Pacer guide · TanStack Router best practices · TanStack Query WebSocket guide