Site icon JD Bots

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

Syntax

export const Route = createRootRoute({
	head: () => ({ meta: [<meta tags>], links: [<links>] }),
	notFoundComponent: <NotFound component>,
	shellComponent: <Shell component>,
});

The full list of options is in the createRootRoute reference and RouteOptions. shellComponent is described in TanStack Start’s Selective SSR guide.

What the Root Route Does

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

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)

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>
	);
}

The Head Tags

src/routes/__root.tsx (excerpt)

	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)

	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.tsx

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

Related

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

Exit mobile version