Coder Legion - Recent posts tagged tanstack

Build a Slide-In Mobile Menu in TanStack Start with Tailwind v4

Sun, 18 Oct 2026 18:49:44 +0000

A mobile menu that pops in and out works, but it feels unfinished. In this article we turn it into a drawer that slides in from the right with a fading backdrop, using only Tailwind classes and no animation library. We also keep it usable for keyboard and screen-reader users, lock the page scroll while it is open, and respect the reduced-motion setting.

This is part of the TanStack Start Basics series. It builds on the responsive Header and the separate NavLinks component from the previous part.

You can view the video Here

In the previous part, the mobile menu lived in the Header, underneath the flex container, and the hamburger button toggled it. Delete it. This is the code to remove:

{open && (
  <nav
    id="mobile-menu"
    aria-label="Mobile"
    className="border-t md:hidden"
  >
    <NavLinks
      listClass="flex flex-col px-6 py-2"
      linkClass="block py-3 text-base font-medium text-neutral-600 hover:text-black"
      onNavigate={() => setOpen(false)}
    />
  </nav>
)}

When open is false, React removes this menu from the page completely. A CSS transition needs an element that exists in both the start and end states, so there is nothing to animate. The fix is a side panel that is always on the page, which we slide off screen with Tailwind.

Always render the panel

Here is the side panel. It replaces the old menu in the same position in the header. It uses a cn helper, so you will also need this function in the utils file in your lib folder. If you use shadcn/ui, you already have it. Otherwise, install clsx and tailwind-merge (npm i clsx tailwind-merge) and add:

// src/lib/utils.ts
import type { ClassValue } from 'clsx'
import { clsx } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

The panel also uses the X icon, so add these imports at the top of Header.tsx if you don't have them yet:

import { X } from 'lucide-react'
import { cn } from '@/lib/utils'

<nav
  id="mobile-menu"
  aria-label="Mobile"
  className={cn(
    'fixed inset-y-0 right-0 z-50 w-72 bg-white p-6 shadow-xl md:hidden',
  )}
>
  <button
    type="button"
    onClick={() => setOpen(false)}
    aria-label="Close menu"
    className="mb-6 ml-auto block rounded p-2 hover:bg-gray-100"
  >
    <X className="size-6" />
  </button>
  <NavLinks
    listClass="flex flex-col gap-4"
    linkClass="text-lg text-gray-600 hover:text-black"
    onNavigate={() => setOpen(false)}
  />
</nav>

Make it jump in and out

To move the panel on and off the screen, add Tailwind's translate classes with a ternary on open:

open ? 'translate-x-0' : 'translate-x-full',

Add it as a second argument to cn on the <nav>:

<nav
  id="mobile-menu"
  aria-label="Mobile"
  className={cn(
    'fixed inset-y-0 right-0 z-50 w-72 bg-white p-6 shadow-xl md:hidden',
    open ? 'translate-x-0' : 'translate-x-full',
  )}
>
  {/* the close button and NavLinks stay the same */}
</nav>

The panel now jumps on and off the screen, but it doesn't slide yet.

You may have noticed the helper function cn. It joins class names, skips the ones that are false, and if two Tailwind classes conflict, the last one wins.

Add the backdrop

Next, a dark layer behind the panel. Clicking it closes the menu, which is what people expect from a drawer. It sits one layer below the panel (z-40 against z-50) and covers the whole screen. When the menu is closed it must not catch clicks, so pointer-events-none is not optional here. Without it, an invisible full-screen layer would swallow every tap on the page. Put it right above the <nav>:

<div
  aria-hidden="true"
  onClick={() => setOpen(false)}
  className={cn(
    'fixed inset-0 z-40 bg-black/50 md:hidden',
    open ? 'opacity-100' : 'pointer-events-none opacity-0',
  )}
/>

This is how it should look in your code:

<div
  aria-hidden="true"
  onClick={() => setOpen(false)}
  className={cn(
    'fixed inset-0 z-40 bg-black/50 md:hidden',
    open ? 'opacity-100' : 'pointer-events-none opacity-0',
  )}
/>
<nav
  id="mobile-menu"
  aria-label="Mobile"
  className={cn(
    'fixed inset-y-0 right-0 z-50 w-72 bg-white p-6 shadow-xl md:hidden',
    open ? 'translate-x-0' : 'translate-x-full',
  )}
>
  <button
    type="button"
    onClick={() => setOpen(false)}
    aria-label="Close menu"
    className="mb-6 ml-auto block rounded p-2 hover:bg-gray-100"
  >
    <X className="size-6" />
  </button>
  <NavLinks
    listClass="flex flex-col gap-4"
    linkClass="text-lg text-gray-600 hover:text-black"
    onNavigate={() => setOpen(false)}
  />
</nav>

Make it slide

Now the fun part, and it takes two classes. transition-transform tells the browser to animate changes to the position, duration-300 makes it take 300 milliseconds, and ease-out makes it start fast and settle gently. The backdrop gets the same treatment, but it fades, so it uses transition-opacity.

Add this to the panel:

transition-transform duration-300 ease-out

Add this to the backdrop:

transition-opacity duration-300

Your code should look like this:

<div
  aria-hidden="true"
  onClick={() => setOpen(false)}
  className={cn(
    'fixed inset-0 z-40 bg-black/50 transition-opacity duration-300 md:hidden',
    open ? 'opacity-100' : 'pointer-events-none opacity-0',
  )}
/>
<nav
  id="mobile-menu"
  aria-label="Mobile"
  className={cn(
    'fixed inset-y-0 right-0 z-50 w-72 bg-white p-6 shadow-xl transition-transform duration-300 ease-out md:hidden',
    open ? 'translate-x-0' : 'translate-x-full',
  )}
>
  <button
    type="button"
    onClick={() => setOpen(false)}
    aria-label="Close menu"
    className="mb-6 ml-auto block rounded p-2 hover:bg-gray-100"
  >
    <X className="size-6" />
  </button>
  <NavLinks
    listClass="flex flex-col gap-4"
    linkClass="text-lg text-gray-600 hover:text-black"
    onNavigate={() => setOpen(false)}
  />
</nav>

One Tailwind v4 detail: translate-x-* sets the CSS translate property, not transform. In v4, transition-transform includes translate, so this works. If a slide ever refuses to animate, check that your transition covers translate.

Hide the closed panel

It looks right, but there is a catch. The panel is only parked off screen. Press Tab with the menu closed and focus disappears into links you can't see, and a screen reader will still read them out. The fix is the invisible class when the menu is closed.

If we add invisible and nothing else, the panel vanishes the instant you close it, and the slide-out never shows. So we also tell the transition to animate visibility, not just position. The browser keeps the panel visible until the slide finishes, then hides it.

Make two changes to the panel:

Replace transition-transform with transition-[translate,visibility].
Replace translate-x-full with invisible translate-x-full.

Your code should look like this:

<div
  aria-hidden="true"
  onClick={() => setOpen(false)}
  className={cn(
    'fixed inset-0 z-40 bg-black/50 transition-opacity duration-300 md:hidden',
    open ? 'opacity-100' : 'pointer-events-none opacity-0',
  )}
/>
<nav
  id="mobile-menu"
  aria-label="Mobile"
  className={cn(
    'fixed inset-y-0 right-0 z-50 w-72 bg-white p-6 shadow-xl transition-[translate,visibility] duration-300 ease-out md:hidden',
    open ? 'translate-x-0' : 'invisible translate-x-full',
  )}
>
  <button
    type="button"
    onClick={() => setOpen(false)}
    aria-label="Close menu"
    className="mb-6 ml-auto block rounded p-2 hover:bg-gray-100"
  >
    <X className="size-6" />
  </button>
  <NavLinks
    listClass="flex flex-col gap-4"
    linkClass="text-lg text-gray-600 hover:text-black"
    onNavigate={() => setOpen(false)}
  />
</nav>

Stop the page from scrolling

With the drawer open, scrolling still moves the page behind it, which feels sloppy. We already have an effect that listens for the Escape key, so we extend it: lock scrolling when the menu opens, and unlock it in the cleanup. Replace the useEffect from the previous part, the one that closes the menu on Escape, with this:

useEffect(() => {
  if (!open) return

  const onKeyDown = (e: KeyboardEvent) => {
    if (e.key === 'Escape') setOpen(false)
  }

  document.addEventListener('keydown', onKeyDown)
  document.body.style.overflow = 'hidden'

  return () => {
    document.removeEventListener('keydown', onKeyDown)
    document.body.style.overflow = ''
  }
}, [open])

The cleanup function runs when the menu closes and also if the Header ever unmounts, so the page can never get stuck locked.

Respect reduced motion (optional)

Some people turn on "reduce motion" in their system settings because animation makes them dizzy. Tailwind gives us a variant for that, motion-reduce:, so honoring it costs one class per element. If that's you, add motion-reduce:transition-none to the panel and the backdrop, like so.

Panel:

className={cn(
  'fixed inset-y-0 right-0 z-50 w-72 bg-white p-6 shadow-xl transition-[translate,visibility] duration-300 ease-out motion-reduce:transition-none md:hidden',
  open ? 'translate-x-0' : 'invisible translate-x-full',
)}

Backdrop:

className={cn(
  'fixed inset-0 z-40 bg-black/50 transition-opacity duration-300 motion-reduce:transition-none md:hidden',
  open ? 'opacity-100' : 'pointer-events-none opacity-0',
)}

Test it and wrap up

Open the menu: the panel slides in and the backdrop fades.
Click the backdrop: the menu closes.
Open it again and press Escape: it closes.
Open it and click a link: it navigates and closes.
Close the menu and press Tab: focus skips the hidden links.
Open the menu and try to scroll the page: it stays put.
Turn on reduced motion in your system settings: the menu appears with no animation.

Let's recap. We always render the panel and move it with translate. The backdrop fades and closes the menu. transition-[translate,visibility] keeps the slide-out visible, then hides the panel from keyboards and screen readers. We locked the page scroll, and we respect reduced motion. All of it is plain Tailwind classes and one small effect.

Good to know and what to try next

A gotcha: a fixed element is positioned against the viewport unless an ancestor has a transform, filter or backdrop-filter. If your header uses backdrop-blur, move the backdrop and panel outside the <header> element or the drawer will be sized to the header instead of the screen.

Tell screen readers the menu state: the hamburger button from the previous part should announce whether the menu is open. Add aria-expanded and aria-controls (the <nav> already has id="mobile-menu"), and keep the label constant, because the state comes from aria-expanded and a label that flips between "Open" and "Close" can make it get announced twice. If your button already has a label like "Open menu", change it to a fixed one:

<button
  type="button"
  onClick={() => setOpen((o) => !o)}
  aria-expanded={open}
  aria-controls="mobile-menu"
  aria-label="Menu"
>
  {/* your hamburger icon */}
</button>

Try next:

Close the menu automatically when the window grows past the md breakpoint, so the scroll lock can never be left on.
Move focus to the Close button when the menu opens, and back to the hamburger when it closes.
Swap the slide for a left-side drawer by changing right-0 to left-0 and translate-x-full to -translate-x-full.

Next in the series: error handling and a proper not-found page.

Responsive Navigation in TanStack Start: Hamburger Menu and Desktop Navbar

Fri, 16 Oct 2026 02:14:20 +0000

A header that works on a phone and on a desktop is one of the first things every site needs. In this part of the TanStack Start Basics series, we'll build one with inline links on wide screens, a hamburger menu on small ones, and a few accessibility details that are easy to skip.

You can watch the video here: Responsive Navigation. Everything below is the written version.

Write the links once

Start with a single list of links that both menus will read from:

// src/lib/nav.ts
export const navLinks = [
  { to: '/', label: 'Home' },
  { to: '/products', label: 'Products' },
  { to: '/about', label: 'About' },
  { to: '/contact', label: 'Contact' },
] as const;

The as const lets TypeScript treat every to as an exact route, so a typo is a compile error and not a broken link.

Think mobile first

Tailwind is mobile first. Classes without a prefix apply to every screen size, and a prefix such as md: applies from that width upward. So the plan is to style the phone version first, and then add the desktop changes on top:

hidden md:block is hidden on phones and shown from 768px up (the desktop links)
md:hidden is shown on phones and hidden from 768px up (the menu button and the mobile menu)

A separate NavLinks component

Both menus need the same list of links, so it gets its own component. Start with the props type:

// src/types/index.ts
export type NavLinksProps = {
  listClass: string;
  linkClass: string;
  activeClass?: string;
  onNavigate?: () => void;
};

Then the component:

// src/components/NavLinks.tsx
import { Link } from '@tanstack/react-router';
import { navLinks } from '@/lib/nav';
import type { NavLinksProps } from '@/types';

export default function NavLinks({
  listClass,
  linkClass,
  activeClass = 'text-black underline underline-offset-4',
  onNavigate,
}: NavLinksProps) {
  return (
    <ul className={listClass}>
      {navLinks.map((link) => (
        <li key={link.to}>
          <Link
            to={link.to}
            activeOptions={{ exact: link.to === '/' }}
            className={linkClass}
            activeProps={{ className: activeClass }}
            onClick={onNavigate}
          >
            {link.label}
          </Link>
        </li>
      ))}
    </ul>
  );
}

The two class props let each menu style the list its own way. activeClass has a default, so most callers can leave it out, and onNavigate is optional, so the desktop menu doesn't need it. Because the component lives in its own file, you can reuse it later, in a footer for example, without copying anything.

The header

// src/components/Header.tsx
import { useEffect, useState } from 'react';
import { Link } from '@tanstack/react-router';
import { Menu, X } from 'lucide-react';
import NavLinks from '@/components/NavLinks';

export default function Header() {
  const [open, setOpen] = useState(false);

  useEffect(() => {
    if (!open) return;
    const onKeyDown = (e: KeyboardEvent) => {
      if (e.key === 'Escape') setOpen(false);
    };
    window.addEventListener('keydown', onKeyDown);
    return () => window.removeEventListener('keydown', onKeyDown);
  }, [open]);

  return (
    <header className="border-b bg-white">
      <div className="mx-auto flex h-16 max-w-6xl items-center justify-between px-6">
        <Link to="/" className="text-lg font-bold">
          My Store
        </Link>

        <nav aria-label="Main" className="hidden md:block">
          <NavLinks
            listClass="flex items-center gap-6"
            linkClass="text-sm font-medium text-neutral-600 hover:text-black"
          />
        </nav>

        <button
          type="button"
          onClick={() => setOpen((o) => !o)}
          aria-label={open ? 'Close menu' : 'Open menu'}
          aria-expanded={open}
          aria-controls="mobile-menu"
          className="flex size-11 items-center justify-center rounded-md md:hidden"
        >
          {open ? <X className="size-6" /> : <Menu className="size-6" />}
        </button>
      </div>

      {open && (
        <nav
          id="mobile-menu"
          aria-label="Mobile"
          className="border-t md:hidden"
        >
          <NavLinks
            listClass="flex flex-col px-6 py-2"
            linkClass="block py-3 text-base font-medium text-neutral-600 hover:text-black"
            onNavigate={() => setOpen(false)}
          />
        </nav>
      )}
    </header>
  );
}

If you skip this, you'll notice a bug: you tap a link, the page changes, and the menu stays open. The header lives in a layout route, and a layout stays mounted while the pages inside it change, so its state is never reset.

The fix is to close the menu in the link's click handler, which is where the user's action happens. React's documentation recommends handling things caused by a user action in the event handler for that action, and not in an effect. So NavLinks gets an optional onNavigate prop, and only the mobile menu passes () => setOpen(false).

This also closes the menu when you tap the link for the page you're already on, which an effect that watches the path would miss. If you also want the menu to close when the user presses the browser's back button, you can add an effect that watches the path on top of this, but the click handler covers the main case.

Active links

Link knows when it points at the current page, and activeProps lets you style that state. Every path starts with a slash, so the home link would look active everywhere. activeOptions={{ exact: true }} fixes that, and the code above applies it only to the home link.

Accessibility basics

Use a real button for the toggle, with type="button", so the keyboard can reach it
Label it with aria-label, and update the label with the state
Use aria-expanded and aria-controls so assistive technology knows whether the menu is open
Close the menu with the Escape key
Give each nav its own label, so a screen reader user can tell them apart

Use it in the layout

// src/routes/_appLayout.tsx
import { createFileRoute, Outlet } from '@tanstack/react-router';
import Header from '@/components/Header';

export const Route = createFileRoute('/_appLayout')({
  component: AppLayout,
});

function AppLayout() {
  return (
    <>
      <Header />
      <main className="mx-auto max-w-6xl px-6 py-8">
        <Outlet />
      </main>
    </>
  );
}

Try it

Open your browser's device toolbar and drag the width between 375px and 1024px. The hamburger should appear below 768px, and the inline links above it. Tap a link in the mobile menu and check that it closes.

What's next

In the next part, we'll look at slide-in animation and a dark mode toggle. If you got stuck anywhere, leave a comment on the video.

TanStack Start Layouts Explained (Pathless Layout Routes + Outlet)

Mon, 28 Sep 2026 06:41:48 +0000

Layouts let us customize sections of our app based on their purpose, their content, or the look and feel we want. They give us the flexibility to mix things up, get more creative, and offer a really great UI/UX experience to our users.

Navigation benefits the most. With layouts we can change the nav style, content, and links based on the page a user is on. We also get to write DRY (Don't Repeat Yourself) code: build a navigation component once, call it in a layout, and when something needs to change, edit one file and the change propagates throughout the app.

So, enough talk. Let's crack on.

Where we're picking up

This post continues the app we've been building in this series. If you're here for the first time, start with the first post in this TanStack Start series. If you want to keep up with the full stack, you can also go through the Directus series.

Create a simple header

Open the app in VS Code. In src/components, create a file called MainHeader.tsx with the following code:

export default function MainHeader() {
  return <div></div>
}

Inside the div, add another div containing an h1 and a p tag:

export default function MainHeader() {
  return (
    <div>
      <div>
        <h1>Logo</h1>
        <p>This is our navigtion menu</p>
      </div>
    </div>
  )
}

Yes, "navigtion" is missing an "a". That's deliberate, and you'll see why shortly.

Now add some Tailwind CSS classes:

export default function MainHeader() {
  return (
    <div>
      <div className="flex items-center justify-between p-8">
        <h1 className="uppercase font-bold text-2xl">Logo</h1>
        <p>This is our navigtion menu</p>
      </div>
    </div>
  )
}

Approach 1: paste the header into every route

Copy the div and its content from MainHeader:

<div>
  <div className="flex items-center justify-between p-8">
    <h1 className="uppercase font-bold text-2xl">Logo</h1>
    <p>This is our navigtion menu</p>
  </div>
</div>

Paste it into each route component (index, about, and products) above the first h1. For example, in the home route:

import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/')({ component: Home })

function Home() {
  return (
    <div className="p-8">
      <div>
        <div className="flex items-center justify-between p-8">
          <h1 className="uppercase font-bold text-2xl">Logo</h1>
          <p>This is our navigtion menu</p>
        </div>
      </div>

      <h1 className="font-bold text-5xl text-slate-700">Home</h1>
    </div>
  )
}

You should now see the header on every page. As a reminder from the previous post, the home page is http://localhost:3000, and for every other page you add a forward slash and the page name, like /about and /products.

We have a site header. But this isn't a good implementation. Remember the misspelled word? To fix it, we'd have to visit every route and correct it. That's not efficient. Delete the header from every page and let's try something better.

Approach 2: use the MainHeader component

Our site should be back to how it was, without a header. This time, import the MainHeader component in every route and place it above the first h1:

import MainHeader from '@/components/MainHeader'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/about')({
  component: RouteComponent,
})

function RouteComponent() {
  return (
    <div className="p-8">
      <MainHeader />
      <h1 className="font-bold text-5xl text-slate-700">About</h1>
    </div>
  )
}

Now go into MainHeader.tsx and fix "navigtion" to "navigation". One fix, one file, and it shows up across the app. That's a real improvement.

It's still not ideal, though, because we have to remember to add MainHeader to every route component we create.

Approach 3: put the header in `__root.tsx`

There's a way to call the header once and have it available to every route. Remember __root.tsx? It wraps our entire app using the children prop. What if we place the header above children?

First, remove <MainHeader /> from your route components. Then update the root:

// Only the code relevant to this discussion is shown
import MainHeader from '@/components/MainHeader'

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <QueryClientProvider client={queryClient}>
          <MainHeader />
          {children}
        </QueryClientProvider>
        <Scripts />
      </body>
    </html>
  )
}

Visit the home page and you'll see the logo on the left and the nav menu on the right, above the page content. Visit /about and /products and the header is there too.

Is this great? Well, not quite. It's efficient: the component is called once and shows on every route, and changes happen in one place. The limitation is flexibility. If we want a different header depending on the page the user is on, we have to add complexity to this file. A good rule of thumb is to keep __root.tsx as clean and lean as possible.

So delete the header and its import from __root.tsx. There's an even better way: layouts.

Layouts

With layouts you get the efficiency of editing one file and having the change ripple through your app, but you can also have different layouts for different pages and still edit just one file for each.

In src/components, create a layouts folder. Inside it, create AppLayout.tsx:

import { Outlet } from '@tanstack/react-router'
import MainHeader from '../MainHeader'

export default function AppLayout() {
  return (
    <div>
      <MainHeader />
      <div className="max-w-7xl mx-auto p-4">
        <Outlet />
      </div>
    </div>
  )
}

The only part that might seem strange is Outlet. It works the same way as the children prop in __root.tsx: it's a placeholder where the matched child route gets rendered. That's how a layout wraps a route.

Create the layout route

In src/routes, create a file called _appLayout.tsx. TanStack Start will scaffold the route for you. You may see a path conflict error with the home route. Don't worry about it, it clears up once we're done. Update the file:

import AppLayout from '@/components/layouts/AppLayout'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/_appLayout')({
  component: () => {
    return <AppLayout />
  },
  notFoundComponent: () => {
    return <p>This page doesn't exist!</p>
  },
})

Here's what the two options do:

component: what actually renders when a child route matches. Since this is a layout route, AppLayout contains an <Outlet />, the placeholder where whichever child route matched gets rendered.
notFoundComponent: defines not-found handling scoped to this layout. It lets different sections of your app show contextually appropriate "not found" messaging instead of one generic message everywhere.

Move your routes under the layout

How do we add pages to this layout? Through the file names. Rename your route files like this:

_appLayout.index.tsx
_appLayout.about.tsx
_appLayout.products.tsx

Then remove <MainHeader /> from each route component (if you haven't already), since the layout now provides it. The route path inside each file, like createFileRoute('/_appLayout/about'), is updated for you by the router plugin while the dev server is running.

You'll notice the whole app layout has changed. The pages are now displayed at a fixed width instead of the full page. What's happening is that the route components are now nested inside the _appLayout route. You don't see _appLayout in the browser's URL because the leading underscore tells TanStack Router this is a pathless route, in other words, a layout route.

To change the header, edit the header component and it renders across the app. To change the layout structure, change one file.

What if I need a different header for a specific page?

Layouts have you covered. In src/components, create another header component called ProductsHeader.tsx:

export default function ProductsHeader() {
  return (
    <div>
      <div className="flex items-center justify-between p-8">
        <h1 className="uppercase font-bold text-2xl">Logo</h1>
        <p>This is the Products menu</p>
      </div>
    </div>
  )
}

Now create a layout component for it in src/components/layouts called ProductsLayout.tsx:

import { Outlet } from '@tanstack/react-router'
import ProductsHeader from '../ProductsHeader'

export default function ProductsLayout() {
  return (
    <div>
      <ProductsHeader />
      <div className="max-w-7xl mx-auto p-4">
        <Outlet />
      </div>
    </div>
  )
}

The ProductsHeader is now part of ProductsLayout. To make the products route a child of this layout, rename its file from _appLayout.products.tsx to:

_productsLayout.products.tsx

Then, in src/routes, create _productsLayout.tsx:

import ProductsLayout from '@/components/layouts/ProductsLayout'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/_productsLayout')({
  component: () => {
    return <ProductsLayout />
  },
  notFoundComponent: () => {
    return <p>This page doesn't exist!</p>
  },
})

Check the app. The home and about pages share the same header, while the products page has a different one. You could just as easily give the products page an entirely different layout structure, not just a different header.

Summary

Here's what we covered:

Pasting a header into every route works, but a single typo means editing every page.
A reusable component fixes the typo problem, but you still have to add it to every route by hand.
Putting the header in __root.tsx shows it everywhere from one place, but it makes your root file busier, and it's inflexible when pages need different headers.
Layouts give you the best of both: a pathless layout route (a file starting with _) renders a layout component, and that component uses <Outlet /> to render whichever child route matched.

A few things to remember:

The underscore prefix makes a route pathless, so it wraps its children without adding to the URL.
A route file's name decides which layout it lives under, for example _appLayout.about.tsx versus _productsLayout.products.tsx.
You can create as many layouts as your app needs, each with its own header, structure, and not-found handling, and still only edit one file per layout.

In the next post we'll keep building on this app. If you found this helpful, leave a comment or a reaction, and follow the series so you don't miss it.

Happy coding! 🚀

TanStack Start Basics Part 2 — Connecting to Your Directus Backend

Thu, 10 Sep 2026 22:12:24 +0000

Our frontend has been static so far — just hardcoded headings on a few pages. Today we connect it to the Directus backend built earlier in this series, using the official Directus SDK to pull real product data into our TanStack Start app.

Youtube Video - Tanstack Start Basics Part 2

Installing the Directus SDK

There are a few ways to talk to Directus from a frontend — the REST API directly, GraphQL — but the SDK is the cleanest option, and what we're using here.

npm install @directus/sdk

Creating the Directus Helper

Inside src/lib, create a new file: directus.ts.

import { createDirectus, rest } from '@directus/sdk'

export const directus = createDirectus('Your_Directus_Project_URL').with(rest())

createDirectus initializes a connection client between your app and your Directus instance. On its own it starts empty — capabilities get added by chaining .with(). Since we're fetching over standard HTTP REST requests, we pair it with the rest() modifier.

Defining Our First Type

Inside src, create types/index.ts:

export interface Products {
  id: string
  name: string
  brief: string
  description: string
  price: number
  sale: number
  quantity: number
  isOnSale: boolean
  category: string
  image: string
}

Writing the Fetch Function

Back in directus.ts:

import { createDirectus, rest, readItems } from '@directus/sdk'
import type { Products } from '@/types'

export const directus = createDirectus('Your_Directus_Project_URL').with(rest())

export async function getProducts(): Promise<Products[]> {
  return directus.request(
    readItems('products', {
      fields: [
        'id',
        'name',
        'brief',
        'description',
        'price',
        'sale',
        'quantity',
        'isOnSale',
        'category',
        'image',
      ],
    }),
  )
}

readItems is a built-in SDK helper that generates a request for fetching multiple items from a given collection. At this point, TypeScript throws:

Type 'Record<string, any>[]' is not assignable to type 'Products[]'.

Fixing the Schema Error

This happens because the SDK doesn't automatically know your database's actual shape — it needs a Schema type passed into createDirectus:

type Schema = {
  products: Products[]
}

export const directus = createDirectus<Schema>('Your_Directus_Project_URL').with(rest())

This declares that a products collection exists and maps to an array of Products. With this in place, the error resolves — and as a bonus, TypeScript now validates and autocompletes the fields array against this type too.

Fetching the Data — Method 1: TanStack Query

Install it:

npm i @tanstack/react-query

Set it up in __root.tsx:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

// Create a client
const queryClient = new QueryClient()

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <HeadContent />
      </head>
      <body>
        <QueryClientProvider client={queryClient}>
          {children}
        </QueryClientProvider>
        <Scripts />
      </body>
    </html>
  )
}

Why does RootDocument take a children prop, and why wrap it? __root.tsx wraps your entire application — every route (About, Index, Products) gets passed in as children, rendered inside this HTML shell. Wrapping children with the query provider means every nested route and component now has access to TanStack Query.

Now build the component, src/components/Products.tsx:

import { useQuery } from '@tanstack/react-query'

export default function Products() {
  const { data: products, isLoading: loading } = useQuery({
    queryKey: ['product'],
    queryFn: getProducts,
    staleTime: 5 * 60 * 1000,
    gcTime: 15 * 60 * 1000,
    refetchOnWindowFocus: false,
    retry: 2,
    refetchOnMount: true,
  })

  if (loading) {
    return <div className="container mx-auto p-8">Loading...</div>
  }

  return (
    <div>
      <div className="container mx-auto p-8">
        <h1 className="text-4xl font-medium mb-4">Products</h1>
        <div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-6">
          {products?.map((product) => (
            <div key={product.id} className="border rounded-lg p-4">
              <h2 className="text-xl font-bold mb-2">{product.name}</h2>
            </div>
          ))}
        </div>
      </div>
    </div>
  )
}

A quick rundown of the query options:

Option	What it does
`staleTime`	How long fetched data stays "fresh" (5 min) before a refetch is considered
`gcTime`	How long unused data stays cached in memory (15 min) before being cleared
`refetchOnWindowFocus`	Whether switching tabs and back triggers a refetch (off here)
`retry`	Silent retry attempts on failure before giving up (2 here)
`refetchOnMount`	Whether the component checks for stale data and refetches on every mount (on here)

Wire it into the route:

import Products from '@/components/Products'
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/products')({
  component: RouteComponent,
})

function RouteComponent() {
  return (
    <div className="p-8">
      <h1 className="font-bold text-5xl text-slate-700">Products</h1>
      <Products />
    </div>
  )
}

Visit localhost:3000/products — real product data, pulled live from Directus.

Fetching the Data — Method 2: Route Loaders

Loaders work a little differently, and only on routes directly — not on standalone components. Remove the Products component from the route and build it in directly:

import { createFileRoute } from '@tanstack/react-router'
import { getProducts } from '@/lib/directus'

export const Route = createFileRoute('/products')({
  loader: async () => {
    const products = await getProducts()
    return products
  },
  component: RouteComponent,
})

function RouteComponent() {
  const products = Route.useLoaderData()

  return (
    <div className="p-8">
      <h1 className="font-bold text-5xl text-slate-700 mb-4">Products</h1>
      <div className="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-6">
        {products?.map((product) => (
          <div key={product.id} className="border rounded-lg p-4">
            <h2 className="text-xl font-bold mb-2">{product.name}</h2>
          </div>
        ))}
      </div>
    </div>
  )
}

The loader runs getProducts before the route renders, and Route.useLoaderData() pulls that resolved data straight into the component — no loading state needed, since the data's already there by the time the page shows up.

Which One Should You Use?

Both approaches call the exact same getProducts function underneath — the difference is where the fetching happens and how the result reaches your component.

TanStack Query shines for data that changes often or benefits from caching, background refetching, and built-in loading states — great for a snappy feel on repeat visits.

Route loaders fetch before the route even renders, so there's no loading spinner at all. That pairs particularly well with TanStack Start's server-side rendering model, since the data can be resolved as part of the initial render rather than after the fact.

Summary

In this part, we:

Installed and configured the Directus SDK
Typed our data with a Products interface and a Schema
Built our first real fetch function using readItems
Rendered a live products grid two different ways — TanStack Query and a route loader

Right now we're only displaying each product's name, but this same pattern carries directly into fuller product cards next — pricing, images, sale badges, and eventually branding and tags once those relational fields come into play.

Found this useful? Follow for more Directus and TanStack Start tutorials, or check out the video version above.

Setting Up Our Frontend with TanStack Start

Tue, 08 Sep 2026 15:45:44 +0000

We've finished our backend series — a Directus instance running on a VPS managed by Coolify, backed by PostgreSQL and Redis, with a products collection already built and secured with roles and permissions.

Now it's time to build a frontend to actually display that data. For this, we're using TanStack Start, Tailwind CSS, and shadcn/ui. This post covers getting TanStack Start installed and running.

What Is TanStack Start?

Straight from the official docs:

TanStack Start is a full-stack React framework powered by TanStack Router. It provides full-document SSR, streaming, server functions, client/server builds, and more. With Vite and Rsbuild support, it's ready to develop and deploy to the hosting provider or runtime you want.

In short: it offers the same kind of full-stack capability as frameworks like Next.js or Remix, built on top of TanStack Router.

Creating the Project

First, create a folder for your app. I'm naming mine app_fe — "fe" for front end.

Naming convention tip: I use <app-name>_fe for all my frontend project folders — so an e-commerce project would be store_fe. Makes the folder's purpose obvious at a glance.

From inside that folder, run:

npx @tanstack/cli@latest create .

Note the trailing dot. Since we created the folder ourselves beforehand, the dot tells the CLI to install directly into the current directory. Omit the dot if you'd rather the CLI create a new folder for you.

Walking Through the Setup Prompts

The CLI will walk you through a series of choices:

Prompt	Selection
Select Framework	React
Select Toolchain	ESLint
Select Deployment Adapter	None (self-hosting on our own VPS)
Include demo/example pages?	No
What add-ons would you like?	shadcn/ui
Initialize a new git repository?	Yes
Continue with these settings?	Yes

Wait for the install to finish.

Running the App

Navigate into your app directory (if you aren't already there) and run:

npm run dev

Open your browser to http://localhost:3000. Congratulations — your TanStack Start app is up and running.

Editing the Home Page

Open src/routes/index.tsx. Delete everything inside the div, and save — your home page should now be completely blank. This file is your landing page, the first thing visitors see.

Add an h1 tag inside the empty div:

<h1>Home</h1>

Save, and you'll see "Home" rendered on the page. Now let's add some Tailwind styling:

<h1 className="font-bold text-5xl text-slate-700">Home</h1>

Save again — notice Tailwind works right out of the box, no extra configuration needed.

File-Based Routing

TanStack Start runs on TanStack Router, which uses file-based routing. Every file added to the routes folder automatically becomes a navigable page.

Adding an About Page

Create src/routes/about.tsx:

<div className="p-8">
  <h1 className="font-bold text-5xl text-slate-700">About</h1>
</div>

Save, then visit http://localhost:3000/about. Notice the home page lives at localhost:3000/, and the about page lives at localhost:3000/about — TanStack Start handled that routing automatically, purely based on the filename.

Adding a Products Page

Create src/routes/products.tsx the same way:

<div className="p-8">
  <h1 className="font-bold text-5xl text-slate-700">Products</h1>
</div>

Visit localhost:3000/products, and there's your new page. That's as simple as basic routing gets — there's plenty more you can do with nested and dynamic routes, which we'll cover as it becomes relevant.

What Is That `__root.tsx` File?

You've probably noticed a file called __root.tsx sitting in your routes folder. Here's the simplest way to think about it:

Picture any large website — Amazon, YouTube, anything. Every page has a header up top and often a footer at the bottom that never change, no matter what page you're on. But the content in the middle changes depending on where you navigated.

__root.tsx is the file that builds that "never changes" part. It's the frame around every page in your app. Every route you build — home, about, products — gets rendered inside this one file. Write it once, and every page automatically inherits it.

A word of caution: this file is central to how TanStack Router works under the hood. Avoid modifying it until you understand exactly what each piece does — we'll take a closer look at it in an upcoming post, exactly when it becomes relevant to what we're building.

Summary

In this part, we:

Installed and configured a new TanStack Start project
Ran it locally and confirmed Tailwind works out of the box
Learned file-based routing by building About and Products pages
Got introduced to __root.tsx, the file behind every page in the app

That wraps up our frontend setup. Next up, we'll start pulling real data from our Directus backend into this frontend — connecting everything we've built across this series.

Found this useful? Follow for more Directus and TanStack Start tutorials, or check out the video version above.

Coder Legion - Recent posts tagged tanstack

Build a Slide-In Mobile Menu in TanStack Start with Tailwind v4

Remove the old mobile menu

Always render the panel

Make it jump in and out

Add the backdrop

Make it slide

Hide the closed panel

Stop the page from scrolling

Respect reduced motion (optional)

Test it and wrap up

Good to know and what to try next

Responsive Navigation in TanStack Start: Hamburger Menu and Desktop Navbar

Write the links once

Think mobile first

A separate NavLinks component

The header

Closing the menu when you navigate

Active links

Accessibility basics

Use it in the layout

Try it

What's next

TanStack Start Layouts Explained (Pathless Layout Routes + Outlet)

Where we're picking up

Create a simple header

Approach 1: paste the header into every route

Approach 2: use the MainHeader component

Approach 3: put the header in __root.tsx

Layouts

Create the layout route

Move your routes under the layout

What if I need a different header for a specific page?

Summary

TanStack Start Basics Part 2 — Connecting to Your Directus Backend

Installing the Directus SDK

Creating the Directus Helper

Defining Our First Type

Writing the Fetch Function

Fixing the Schema Error

Fetching the Data — Method 1: TanStack Query

Fetching the Data — Method 2: Route Loaders

Which One Should You Use?

Summary

Setting Up Our Frontend with TanStack Start

What Is TanStack Start?

Creating the Project

Walking Through the Setup Prompts

Running the App

Editing the Home Page

File-Based Routing

Adding an About Page

Adding a Products Page

What Is That __root.tsx File?

Summary

Approach 3: put the header in `__root.tsx`

What Is That `__root.tsx` File?