Site, Navigation & Metadata
Configure site identity, navigation, SEO metadata, and Cloudflare branding.
Most rebranding starts in src/config, while route-level SEO is built by
src/lib/seo.ts. Keep those values aligned with the public Worker origin and
the brand assets in public.
Configuration files
| File | What to customize |
|---|---|
src/config/website-config.ts | Name, description, application name, site URL, OG image, keywords, social profiles, sender, support inbox |
src/config/social-config.ts | Converts configured profiles and support email into icon links |
src/config/footer-config.ts | Product, resource, company, and legal footer groups |
src/config/route-config.ts | Shared Routes constants used by navigation and auth redirects |
src/config/user-sidebar-config.ts | Dashboard groups and role visibility; demo mode can expose admin navigation |
src/config/docs-sidebar-config.ts | Explicit documentation sidebar links |
src/config/docs-common-config.ts | Docs title, description, home/docs links, repository link, sidebar defaults |
Use Routes for stable application paths rather than scattering strings across
components. Locale-aware UI should pass those paths through LocaleLink,
localizePath, or useLocaleRouter.
Sidebar role visibility is presentation, not authorization. The admin route
still needs requireAdmin in beforeLoad, and its API must verify the role.
SEO in TanStack Start
There is no Next.js metadataBase or opengraph-image.tsx convention here.
src/lib/seo.ts exports buildSeoMeta(), and route head() functions merge its
meta and links arrays into the document head:
export const Route = createFileRoute("/{-$locale}/_marketing/about")({
head: () =>
buildSeoMeta({
title: "About",
description: "Learn about the product.",
path: "/about",
}),
component: AboutPage,
})The helper builds titles, descriptions, robots directives, Open Graph and Twitter metadata, canonical links, and locale alternates. For articles it also accepts publication/modification dates and tags.
The canonical origin currently comes from
websiteConfig.metadata.siteUrl. BETTER_AUTH_URL independently controls the
Better Auth origin. Set both to the same deployed origin (for example,
https://app.example.com) so canonical URLs, auth links/cookies, OAuth
callbacks, and public routes agree.
metadata: {
siteUrl: "https://app.example.com",
ogImage: "/og.png",
}src/routes/sitemap[.]xml.ts serves /sitemap.xml. It combines fixed marketing
paths with localized blog, legal, and docs pages, escapes XML, and returns a
one-hour public cache header. Add new indexable application routes to its
marketingPaths list or its appropriate content source.
Rebrand checklist
Replace identity and assets
Update websiteConfig and replace the logo, favicon, OG image, and other assets
under public. Remove stale keywords and the placeholder social profiles.
Update communication identities
Set websiteConfig.mail.fromEmail to an address on your verified sending domain
and supportEmail to the inbox that receives contact messages. Update legal
content and company references inside the React Email templates.
Review navigation
Edit the footer, dashboard sidebar, docs links, and Routes constants together.
Test internal links in both English and Chinese; keep authorization separate
from menu visibility.
Align public origins
Set websiteConfig.metadata.siteUrl, production BETTER_AUTH_URL, OAuth
callbacks, and provider webhook/callback URLs to the same public origin. Review
every route head() after changing a public path.
Rename the Cloudflare deployment
Change name, custom-domain routes, and the BETTER_AUTH_URL vars entry in
wrangler.jsonc. If you rename D1 or R2 resources, update their configuration
and database migration command too.
Verify
- Page titles, descriptions, canonical links, and locale alternates use the new domain.
-
/sitemap.xmlcontains the expected English, Chinese, blog, legal, and docs URLs. - Logo, favicon, OG image, footer, social links, and support address are yours.
- Dashboard navigation respects roles, while protected routes and APIs reject unauthorized users.
- Auth callbacks and cookies work on the same origin used by SEO.