Quick Start

Purpose and Scope

This page gives the shortest practical path from an empty workspace to a working TanStack Router app. The upstream quick-start is intentionally task oriented: it first recommends scaffolding a new project, then explains the two routing styles, and finally covers manual installation for an existing React or Solid project. Use this page when you want to choose between a generated starter and an incremental install without reading the entire routing guide first. It focuses on the first decisions you must make: framework, route configuration style, TypeScript expectations, and development-server handoff.

Sources: docs/router/quick-start.md

Relevant Source Files

docs/router/quick-start.md — Defines the official Router quick-start flow, including the scaffold command, setup prompts, file-based and code-based routing options, framework requirements, and manual installation package names.

Core Primitives

TanStack Router starts with a route configuration: the structure that tells the router which UI and data behavior belong to each URL. In a file-based setup, that structure is derived from route files, so the project layout becomes the primary authoring surface. In a code-based setup, you define the route configuration programmatically, which can be useful when you want complete control over how routes are assembled. The quick-start presents both options as first-class choices while recommending file-based route generation for most projects because it balances performance, simplicity, and developer experience.

Sources: docs/router/quick-start.md

The second primitive is framework binding. The quick-start names React and Solid as the currently supported frameworks for this path, with framework-specific packages and requirements. React users install the React Router package and need React with ReactDOM support for modern root creation. Solid users install the Solid Router package and need a compatible Solid version. TypeScript is not described as mandatory, but the quick-start recommends recent TypeScript for the best experience, which matters because Router’s value proposition is strongly tied to typed routes, params, search state, loaders, and navigation.

Sources: docs/router/quick-start.md

New Project Scaffold

For a new app, the fastest path is to let the TanStack CLI generate the project. The quick-start calls this the impatient path because it avoids hand-wiring dependencies and asks a short series of setup questions instead. Those prompts cover whether you want file-based or code-based routes, whether TypeScript should be included, whether Tailwind CSS should be integrated, how the toolchain should be set up, and whether Git should be initialized. When the CLI finishes, the project already has TanStack Router installed and is ready for local development.

Sources: docs/router/quick-start.md

# React
@tanstack/cli create --router-only
 
# Solid
@tanstack/cli create --router-only --framework solid

After scaffolding, move into the generated project directory and start the development server using the package manager and scripts created by the template. The quick-start does not prescribe a single package-manager command at this point because the scaffolded output can vary based on the selected toolchain. The important handoff is conceptual: once the CLI has created the project, the next step is no longer installing Router; it is opening the generated app, inspecting its route configuration, and beginning to edit routes in the style you selected during setup.

Sources: docs/router/quick-start.md

Choosing File-Based or Code-Based Routing

Choose file-based route generation when you want the route tree to follow your file structure. This is the recommended option for most projects in the quick-start. It reduces the amount of route assembly code you write manually and gives the framework enough structure to provide a strong development experience. It is especially appropriate for teams that want route discovery to be obvious from the project tree, for applications where nested UI follows nested URLs, and for projects that value convention over a fully custom route-building layer.

Sources: docs/router/quick-start.md

Choose code-based route configuration when you prefer to construct routes directly in application code. The quick-start describes this approach as giving full control over routing logic. That control can be useful when routes are generated from application data, when you want to centralize route definitions in a particular module, or when you are learning Router concepts without introducing file conventions immediately. The tradeoff is that you take more responsibility for organizing the route tree yourself, whereas file-based routing lets the filesystem carry more of that structure.

Sources: docs/router/quick-start.md

Existing Project Installation

If you already have a compatible app, you can install Router manually instead of scaffolding. The quick-start separates this path from the new-project path because you should first verify framework requirements. React projects need React version eighteen or later with modern root creation support and ReactDOM version eighteen or later. Solid projects need Solid version one. The documentation also recommends TypeScript version five point three or higher, while noting that TypeScript is not strictly required. In practice, using current TypeScript helps avoid avoidable friction when adopting Router’s typed APIs.

Sources: docs/router/quick-start.md

# React package
@tanstack/react-router
 
# Solid package
@tanstack/solid-router

After installation, verify that the dependency was written to the project manifest. For React, the dependency should be the React Router package. For Solid, it should be the Solid Router package. The quick-start’s verification step is intentionally simple because installation is only the first part of adoption; the next work is creating the root route, adding child routes, and mounting the router provider according to the framework guide. If your project is not React or Solid, treat this quick-start as a signal that official compatibility is limited and follow the project’s contribution or community channels for framework expansion.

Sources: docs/router/quick-start.md

Recommended Next Steps

After completing the quick start, continue with the routing style you selected. File-based users should read the file-based routing guide to understand route file naming, generated route trees, and how route files compose. Code-based users should read the code-based routing material to see how route objects are defined and connected. From there, move into type safety, path params, search params, data loading, and navigation. Those topics explain why the initial setup choices matter: they determine how URLs, data, links, loaders, and route components stay connected as the app grows.

Sources: docs/router/quick-start.md

Ask a question...