Skip to main content
0 reactions

The Root Route in TanStack Start: What __root.tsx Does

Card titled The Root Route: __root.tsx, showing a frame labelled __root.tsx around a header with Home, Books and About links and a dashed area marked your page goes here.
The root route in TanStack Start.

Every TanStack Start app has a file named __root.tsx in src/routes. It’s the root route: the one route that’s always there, wrapped around every page of your app. This post explains what it does, part by part, using the root route of a real app, the Bookshop.

By the end, you’ll know where to put the parts every page shares: the HTML document, the head tags, a header and the 404 page.

Syntax

SyntaxTypeScript
export const Route = createRootRoute({
	head: () => ({ meta: [<meta tags>], links: [<links>] }),
	notFoundComponent: <NotFound component>,
	shellComponent: <Shell component>,
});
  • createRootRoute creates the root route. It takes the same options as any other route, except the ones about an address, because the root route has none.
  • head returns the tags for the page’s <head>: meta tags such as the title, and links such as a stylesheet.
  • notFoundComponent is the page shown when no page matches the address.
  • shellComponent is the HTML document around every page. It always renders on the server, and it wraps the page, the error page and the not-found page.

The full list of options is in the createRootRoute reference (opens in a new tab) and RouteOptions (opens in a new tab). shellComponent is described in TanStack Start’s Selective SSR guide (opens in a new tab).

What the Root Route Does

  • It has no address, and it always matches, whatever page is open.
  • It always renders, so it’s the place for the parts every page shares.
  • It must be named __root.tsx and sit at the top of src/routes.

In the Bookshop, the header with the links comes from __root.tsx, and the rest of each page from its own file:

The Bookshop About page with the header links Home, Books and About above it, with About in bold.
The header comes from __root.tsx; the rest of the page comes from about.tsx.

The Shell: html, head and body

The Bookshop’s shell component is RootDocument. It returns the whole HTML document:

src/routes/__root.tsx (excerpt)TypeScript
function RootDocument({ children }: { children: React.ReactNode }) {
	return (
		<html lang="en">
			<head>
				<HeadContent />
			</head>
			<body>
				<header className="border-b border-gray-200">
					<nav className="mx-auto flex max-w-2xl gap-6 px-8 py-4 text-lg">
						<Link to="/" activeProps={{ className: "font-bold" }}>
							Home
						</Link>
						<Link to="/books" activeProps={{ className: "font-bold" }}>
							Books
						</Link>
						<Link to="/about" activeProps={{ className: "font-bold" }}>
							About
						</Link>
					</nav>
				</header>
				{children}
				<TanStackDevtools
					config={{
						position: "bottom-right",
					}}
					plugins={[
						{
							name: "Tanstack Router",
							render: <TanStackRouterDevtoolsPanel />,
						},
					]}
				/>
				<Scripts />
			</body>
		</html>
	);
}
  • children is the page that’s open. The shell puts it inside <body>, below the header.
  • <HeadContent /> writes the tags from head. It belongs in <head>.
  • <Scripts /> loads the app’s JavaScript in the browser. It belongs at the end of <body>, and TanStack Start’s docs say to always include it.
  • TanStackDevtools adds the devtools button you see while you develop. Production builds leave it out.

The Head Tags

src/routes/__root.tsx (excerpt)TypeScript
	head: () => ({
		meta: [
			{
				charSet: "utf-8",
			},
			{
				name: "viewport",
				content: "width=device-width, initial-scale=1",
			},
			{
				title: "TanStack Start Starter",
			},
		],
		links: [
			{
				rel: "stylesheet",
				href: appCss,
			},
		],
	}),

These tags apply to every page: the character set, the viewport setting that makes the page fit a phone, the page title and the stylesheet. Each page can also add its own head tags; Part 26 of the series covers that.

The 404 Page

src/routes/__root.tsx (excerpt)TypeScript
	notFoundComponent: NotFound,
	shellComponent: RootDocument,
});

function NotFound() {
	return (
		<main className="mx-auto max-w-2xl p-8">
			<h1 className="text-4xl font-bold">Page not found</h1>
			<p className="mt-4 text-lg">There is no page at this address.</p>
			<Link to="/" className="mt-4 inline-block text-lg underline">
				Go to the home page
			</Link>
		</main>
	);
}

notFoundComponent shows NotFound when no page matches the address. The shell still wraps it, so the header stays on the 404 page too.

The Complete File

src/routes/__root.tsxTypeScript
import { TanStackDevtools } from "@tanstack/react-devtools";
import {
	createRootRoute,
	HeadContent,
	Link,
	Scripts,
} from "@tanstack/react-router";
import { TanStackRouterDevtoolsPanel } from "@tanstack/react-router-devtools";

import appCss from "../styles.css?url";

export const Route = createRootRoute({
	head: () => ({
		meta: [
			{
				charSet: "utf-8",
			},
			{
				name: "viewport",
				content: "width=device-width, initial-scale=1",
			},
			{
				title: "TanStack Start Starter",
			},
		],
		links: [
			{
				rel: "stylesheet",
				href: appCss,
			},
		],
	}),
	notFoundComponent: NotFound,
	shellComponent: RootDocument,
});

function NotFound() {
	return (
		<main className="mx-auto max-w-2xl p-8">
			<h1 className="text-4xl font-bold">Page not found</h1>
			<p className="mt-4 text-lg">There is no page at this address.</p>
			<Link to="/" className="mt-4 inline-block text-lg underline">
				Go to the home page
			</Link>
		</main>
	);
}

function RootDocument({ children }: { children: React.ReactNode }) {
	return (
		<html lang="en">
			<head>
				<HeadContent />
			</head>
			<body>
				<header className="border-b border-gray-200">
					<nav className="mx-auto flex max-w-2xl gap-6 px-8 py-4 text-lg">
						<Link to="/" activeProps={{ className: "font-bold" }}>
							Home
						</Link>
						<Link to="/books" activeProps={{ className: "font-bold" }}>
							Books
						</Link>
						<Link to="/about" activeProps={{ className: "font-bold" }}>
							About
						</Link>
					</nav>
				</header>
				{children}
				<TanStackDevtools
					config={{
						position: "bottom-right",
					}}
					plugins={[
						{
							name: "Tanstack Router",
							render: <TanStackRouterDevtoolsPanel />,
						},
					]}
				/>
				<Scripts />
			</body>
		</html>
	);
}

Common Mistakes

MistakeWhat happensDo this instead
Renaming or moving __root.tsxTanStack Start looks for the root route under exactly that name, at the top of src/routesKeep the name and the place
Removing <Scripts />The app’s JavaScript doesn’t load in the browserKeep it at the end of <body>
Putting one page’s content in the root routeIt shows on every pagePut it in that page’s own file in src/routes

FAQ

What’s the difference between shellComponent and component? shellComponent is the HTML document and always renders on the server. component is the root route’s own content inside it, and it defaults to <Outlet />, the open page. The Bookshop sets only shellComponent, so each page goes straight into children.

Can an app have more than one root route? No. The root route is the top of the route tree, and every other route sits under it.

What if only some pages need the header? Then the header belongs in a layout route that wraps just those pages. Part 6 of the series covers layouts.

Conclusion

__root.tsx is the frame around every page: the HTML document, the head tags, the shared header and the 404 page. Put something here only when every page needs it.

Additional Resources

TanStack, React and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by TanStack.

0 comments