TanStack Router vs. Next.js App Router: File-Based Routing Compared

Hello! Welcome back.

In our last lesson, we explored how TanStack Start uses the Vinxi bundler to create separate server and client builds, enabling Server-Side Rendering and client-side hydration. This foundational knowledge of the build process is crucial as we now turn our attention to how we actually define the pages and structure of our application.

Lesson 3: File-Based Routing Conventions

Today's Goal:

This lesson directly addresses your goal of mastering TanStack Router by focusing on one of its most visible features. By the end of this session, you will be able to compare TanStack Router's file-based routing conventions with Next.js App Router patterns.

As an experienced front-end lead, you've likely worked with or encountered the file-based routing paradigm popularized by Next.js. We will use that as a reference point to understand the similarities, differences, and unique advantages of TanStack Router's approach.

What we will cover:

1. A Hybrid Philosophy: Understanding why TanStack Router is a "code-first" router that offers a file-based experience.
2. Core Conventions: A side-by-side comparison of routing patterns in TanStack Router and Next.js App Router.
3. Unique TanStack Patterns: Exploring flexible conventions like flat-file nesting and dot notation.

1. The "Best of Both Worlds" Philosophy

File-based routing is praised for its discoverability but sometimes criticized for its rigidity and lack of type safety. TanStack Router aims to solve this by not being a pure file-based router at its core.

• Next.js: Is fundamentally a file-based router. The file system is the route definition.
• TanStack Router: Is fundamentally a code-first router. You can define your entire route tree in a single TypeScript file if you wish. However, TanStack Start comes pre-configured with a Vite plugin (@tanstack/router-vite-plugin) that generates this code for you by watching your src/routes directory.

This gives you the convenience of file-based routing while retaining the full power and type safety of a programmatic, code-first approach. The generated configuration lives in src/routeTree.gen.ts—a file you should not edit manually, but which is the "source of truth" for the router at runtime.

The following video from Theo - t3.gg captures the reaction of an experienced developer discovering this hybrid approach and its benefits.

This generated route tree is what enables the powerful type-safety features we will explore in upcoming lessons, such as autocompletion for the <Link> component's to prop.

2. Core Routing Patterns: A Side-by-Side Comparison

Let's break down the most common routing patterns by comparing TanStack Router's conventions with the Next.js App Router. This will help you map your existing knowledge to the TanStack ecosystem.

For a detailed reference on the Next.js patterns mentioned below, you can review the following article.

Here is a comparative table of the core conventions:

| Feature | TanStack Router (src/routes/) | Next.js App Router (src/app/) - |
| Root Layout | _root.tsx | layout.tsx - |
| Index/Home Page | index.tsx | page.tsx - |
| Basic Route (/about) | about.tsx | about/page.tsx - |
| Nested Route Layout | Folder posts/, with route.tsx containing <Outlet /> | Folder posts/, with layout.tsx containing {children} - |
| Dynamic Segment | posts/$postId.tsx or posts/[postId]/... | posts/[postId]/... - |
| Route Group | (marketing)/about.tsx → /about | (marketing)/about/page.tsx → /about - |
| Pathless Layout | _auth/route.tsx (folder is ignored in URL) | (auth)/layout.tsx (uses a route group) - |
| Catch-all (Splat) | posts/$.tsx → matches /posts/* | posts/[...slug]/page.tsx → matches /posts/* - |
| Optional Catch-all | posts/[[...slug]].tsx → matches /posts and /posts/* | posts/[[...slug]]/page.tsx → matches /posts and /posts/* - |

Key Differences to Note:

• File vs. Folder: TanStack Router often uses a single file (about.tsx) where Next.js would use a folder with a page.tsx file inside (about/page.tsx). This can lead to a flatter, less nested file structure in TanStack projects.
• Layout File Name: TanStack Router uses _root.tsx for the top-level layout and route.tsx for nested layouts. Next.js consistently uses layout.tsx.
• Dynamic Segment Syntax: TanStack Router prefers the dollar sign ($postId) for dynamic segments in filenames, though it also supports the bracket syntax ([postId]) for folder names. The $ is often cleaner for flat-file structures.

3. TanStack Router's Unique & Flexible Patterns

Beyond the direct comparisons, TanStack Router offers some unique conventions that provide extra flexibility.

a) Flat-File Nesting

You can create nested routes without creating nested folders by using dot notation in your filenames. This is excellent for co-locating related routes.

• Goal: Create routes for /contact, /contact/usa, and /contact/usa/new-york.
• Folder-based approach:

  /contact
    - route.tsx
    /usa
      - route.tsx
      /new-york
        - route.tsx
  

• TanStack's Flat-File approach:

  contact.tsx
  contact.country.tsx
  contact.country.city.tsx
  

  In this case, country and city would be dynamic segments, so the actual filenames would be contact.$country.tsx and contact.$country.$city.tsx. This keeps related logic in the same directory level.

b) Escaping a Layout with Dot Notation

Sometimes you want a URL to be nested (/categories/create) but you don't want it to share the parent layout (/categories). TanStack has an elegant solution for this.

• Layout Route: categories/route.tsx
• Child Route: categories/laptops/route.tsx (Renders inside the categories layout)
• Escaped Route: categories.create.tsx (Renders at /categories/create but does not use the categories/route.tsx layout)

This is a powerful feature for "one-off" pages like creation or edit forms that belong to a resource but require a different UI.

To see these conventions in action, let's turn to a comprehensive tutorial that builds a full application.

Conclusion

You've now seen how TanStack Router's file-based routing system provides a familiar yet more flexible alternative to what you might know from Next.js. It successfully combines the organizational benefits of file-system conventions with the type-safety and power of a programmatic router.

Key Takeaways:

• TanStack Router uses a Vite plugin to generate a typed route tree from your file system, offering a hybrid file-based and code-first approach.
• Many conventions, like route groups () and dynamic segments [], have direct parallels with the Next.js App Router.
• Key differences include using single files for routes (about.tsx), _root.tsx/route.tsx for layouts, and $ for dynamic segments.
• TanStack Router offers unique, flexible patterns like flat-file nesting (posts.$postId.tsx) and layout escaping (posts.create.tsx).

Next Lesson Preview:

Understanding the file structure is the first step. The real power of TanStack Router shines when you start working with data. In our next lesson, we will "Create typed route definitions with path parameters and search params." You'll see how the router automatically infers types from your URL, providing compile-time safety for accessing path and search parameters.