OpenWikitanstack/router

Basic and File-Based Examples

Purpose and Scope

This page helps you recognize the smallest working TanStack Router application shape before moving into larger guides. The repository evidence here focuses on file-based routing driven by the Router CLI and on end-to-end examples that mount generated route trees in React, Solid, and Vue. A basic Router app has three recurring parts: a generated or manually assembled route tree, a router instance created from that tree, and a framework-specific provider mounted into the application root. The examples are intentionally small so that route generation, type registration, and rendering are easy to see together.

Sources: docs/router/installation/with-router-cli.md, e2e/react-router/generator-cli-only/src/main.tsx, e2e/solid-router/generator-cli-only/src/main.tsx, e2e/vue-router/generator-cli-only/src/main.tsx

File-based examples are especially useful when you want conventions to create the route tree for you. The CLI documentation says the TanStack Router CLI should be used when a supported bundler integration is not in play, and it only generates the route tree file. That constraint matters: the CLI is not a dev server, a compiler, or a full build integration. In the minimal examples, application code imports the generated route tree and then configures normal router behavior such as intent preloading, stale time, and scroll restoration.

Sources: docs/router/installation/with-router-cli.md, e2e/react-router/generator-cli-only/src/main.tsx

Relevant Source Files

  • docs/router/installation/with-router-cli.md — Documents when to use the Router CLI, how to add route generation scripts, the available generate and watch commands, default configuration, and guidance for ignoring the generated route tree file.
  • e2e/react-router/generator-cli-only/src/main.tsx — Shows a minimal React entry point that imports routeTree, creates a router, registers router types, and renders RouterProvider.
  • e2e/react-router/generator-cli-only/src/routes/index.tsx — Shows the root file route for the React CLI-only example using createFileRoute('/') and a simple Home component.
  • e2e/solid-router/generator-cli-only/src/main.tsx — Shows the Solid equivalent entry point with createRouter, RouterProvider, type registration, and solid-js/web rendering.
  • e2e/solid-router/generator-cli-only/src/routes/index.tsx — Shows the Solid root file route using createFileRoute('/') and Solid JSX attributes.
  • e2e/vue-router/generator-cli-only/src/main.tsx — Shows the Vue equivalent entry point using createApp and a setup function that returns RouterProvider.

Minimal File-Based Flow

Start with the CLI when your project needs file-based routing but does not use a supported Router bundler plugin. Install the package as a development dependency, then add scripts that call the command line entry point. The documented pattern separates one-time generation from continuous watching: generate before a production build, and watch while developing. When watch mode is running, route files under the configured routes directory are observed so that additions, removals, and edits produce a fresh route tree. The generated file is then imported by the app entry point.

Sources: docs/router/installation/with-router-cli.md

{
  "scripts": {
    "generate-routes": "tsr generate",
    "watch-routes": "tsr watch",
    "build": "npm run generate-routes && ...",
    "dev": "npm run watch-routes && ..."
  }
}

The default CLI configuration is deliberately conventional. Routes live under a source routes directory, the generated tree is written into source as a generated TypeScript file, ignored route files can use a configured prefix, and the target framework is part of the configuration. For readers studying examples, the important point is that the application does not hand-write the complete tree in the entry file. The route modules declare their own file routes, the generator discovers them, and the app imports the finished route tree from the generated module.

Sources: docs/router/installation/with-router-cli.md

React Example Anatomy

The React CLI-only example demonstrates the common Router runtime setup in its most compact form. It imports React, the React DOM client, createRouter and RouterProvider from the React package, and routeTree from the generated module. The router instance is created with that tree plus defaults for intent preloading, stale time, and scroll restoration. After creation, the example augments the package Register interface so TypeScript can associate application calls with this exact router instance. Finally, ReactDOM creates a root and renders RouterProvider inside React StrictMode.

Sources: e2e/react-router/generator-cli-only/src/main.tsx

const router = createRouter({
  routeTree,
  defaultPreload: 'intent',
  defaultStaleTime: 5000,
  scrollRestoration: true,
})

The matching route file is even smaller, which is the point of the example. It imports createFileRoute from the React Router package, exports a Route created for the root path, and assigns a Home component. That exported Route is the unit the generator consumes when building the generated tree. The component itself only renders a welcoming heading, but the structure scales to loaders, validation, context, and nested route modules. When debugging a new app, confirm that the route module exports Route and that the generated tree is imported by the entry point.

Sources: e2e/react-router/generator-cli-only/src/routes/index.tsx

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

Solid and Vue Variants

The Solid example follows the same Router shape while using Solid’s rendering primitives. It imports createRouter and RouterProvider from the Solid Router package, imports routeTree from the generated module, and registers the router type through module augmentation. The visible differences are framework integration details: Solid renders with the render function from solid-js/web, and the route component uses Solid JSX conventions such as class rather than className. This makes the example valuable for confirming that Router concepts remain stable while rendering and component syntax follow the host framework.

Sources: e2e/solid-router/generator-cli-only/src/main.tsx, e2e/solid-router/generator-cli-only/src/routes/index.tsx

Vue keeps the same route tree and router instance pattern but mounts through createApp. The example creates a Vue app object with a setup function that returns a render function containing RouterProvider, then mounts the app at the root element. Like React and Solid, it imports routeTree from the generated file and registers router types against the Vue Router package. If you are comparing framework packages, treat createRouter, RouterProvider, the generated route tree import, and Register augmentation as the cross-framework contract; treat the root mounting API as framework-specific.

Sources: e2e/vue-router/generator-cli-only/src/main.tsx

Generated Route Tree Hygiene

Because the route tree file is generated, the CLI documentation recommends excluding it from tools that may modify or distract from generated output. Linters and formatters should not rewrite it, and editors can be configured to mark the generated file as read-only, exclude it from file watching, and remove it from search results. This is not just cosmetic. If a generated file opens with transient errors during route renames, developers may chase noise instead of fixing the route source file. Keep route modules hand-edited and the generated tree machine-managed.

Sources: docs/router/installation/with-router-cli.md

{
  "files.readonlyInclude": {
    "**/routeTree.gen.ts": true
  },
  "files.watcherExclude": {
    "**/routeTree.gen.ts": true
  },
  "search.exclude": {
    "**/routeTree.gen.ts": true
  }
}

Code-Based, File-Based, and Virtual-File Mental Model

A code-based Router example usually teaches the same runtime pieces without the generator: routes are assembled directly in source code, then passed into createRouter. A file-based example moves route discovery and tree assembly into generation, leaving individual route files to declare their own Route exports. A virtual-file route setup, used by plugin integrations elsewhere in the project, keeps the same idea that generated route information is imported by application code, but the bundler can provide it virtually. For this page’s CLI-only examples, the durable lesson is the boundary between generated route structure and ordinary framework rendering.

Sources: docs/router/installation/with-router-cli.md, e2e/react-router/generator-cli-only/src/main.tsx

Next Steps

Use these examples as a checklist when bringing up a new minimal app. First, make route files that export file routes. Second, run generation or watch mode so the route tree exists. Third, import that tree into the framework entry point. Fourth, create and register the router, then mount RouterProvider with the framework’s normal root API. Once this works, move to the file-based routing, route tree, type safety, data loading, and CLI pages to understand nested routes, generated APIs, loaders, and production build integration in more depth.

Ask a question...