diff --git a/docs/router/config.json b/docs/router/config.json index 0b56fa735d6..6eef4eb340b 100644 --- a/docs/router/config.json +++ b/docs/router/config.json @@ -17,10 +17,6 @@ "label": "Overview", "to": "framework/react/overview" }, - { - "label": "Installation", - "to": "framework/react/installation" - }, { "label": "Quick Start", "to": "framework/react/quick-start" @@ -29,18 +25,6 @@ "label": "Devtools", "to": "framework/react/devtools" }, - { - "label": "Comparison", - "to": "framework/react/comparison" - }, - { - "label": "Migrate from React Router", - "to": "framework/react/migrate-from-react-router" - }, - { - "label": "Migrate from React Location", - "to": "framework/react/migrate-from-react-location" - }, { "label": "Decisions on DX", "to": "framework/react/decisions-on-dx" @@ -58,10 +42,6 @@ "label": "Overview", "to": "framework/solid/overview" }, - { - "label": "Installation", - "to": "framework/solid/installation" - }, { "label": "Quick Start", "to": "framework/solid/quick-start" @@ -82,6 +62,66 @@ } ] }, + { + "label": "Installation Guides", + "children": [], + "frameworks": [ + { + "label": "react", + "children": [ + { + "label": "Manual Setup", + "to": "framework/react/installation/manual" + }, + { + "label": "Vite", + "to": "framework/react/installation/with-vite" + }, + { + "label": "Rspack/Rsbuild", + "to": "framework/react/installation/with-rspack" + }, + { + "label": "Webpack", + "to": "framework/react/installation/with-webpack" + }, + { + "label": "Esbuild", + "to": "framework/react/installation/with-esbuild" + }, + { + "label": "Router CLI", + "to": "framework/react/installation/with-router-cli" + }, + { + "label": "Migrate from React Router", + "to": "framework/react/installation/migrate-from-react-router" + }, + { + "label": "Migrate from React Location", + "to": "framework/react/installation/migrate-from-react-location" + } + ] + }, + { + "label": "solid", + "children": [ + { + "label": "Manual Setup", + "to": "framework/solid/installation/manual" + }, + { + "label": "Installation with Vite", + "to": "framework/solid/routing/installation-with-vite" + }, + { + "label": "Installation with the Router CLI", + "to": "framework/solid/routing/installation/with-router-cli" + } + ] + } + ] + }, { "label": "Routing", "children": [], @@ -113,26 +153,6 @@ "label": "Code-Based Routing", "to": "framework/react/routing/code-based-routing" }, - { - "label": "Installation with Vite", - "to": "framework/react/routing/installation-with-vite" - }, - { - "label": "Installation with Rspack/Rsbuild", - "to": "framework/react/routing/installation-with-rspack" - }, - { - "label": "Installation with Webpack", - "to": "framework/react/routing/installation-with-webpack" - }, - { - "label": "Installation with Esbuild", - "to": "framework/react/routing/installation-with-esbuild" - }, - { - "label": "Installation with the Router CLI", - "to": "framework/react/routing/installation-with-router-cli" - }, { "label": "File Naming Conventions", "to": "framework/react/routing/file-naming-conventions" @@ -166,14 +186,6 @@ "label": "Code-Based Routing", "to": "framework/solid/routing/code-based-routing" }, - { - "label": "Installation with Vite", - "to": "framework/solid/routing/installation-with-vite" - }, - { - "label": "Installation with the Router CLI", - "to": "framework/solid/routing/installation-with-router-cli" - }, { "label": "File Naming Conventions", "to": "framework/solid/routing/file-naming-conventions" @@ -418,25 +430,6 @@ } ] }, - { - "label": "How-To", - "children": [], - "frameworks": [ - { - "label": "react", - "children": [ - { - "label": "Install TanStack Router", - "to": "framework/react/how-to/install" - } - ] - }, - { - "label": "solid", - "children": [] - } - ] - }, { "label": "API", "children": [ diff --git a/docs/router/framework/react/comparison.md b/docs/router/framework/react/comparison.md deleted file mode 100644 index d6f5449bb92..00000000000 --- a/docs/router/framework/react/comparison.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Comparison | TanStack Router & TanStack Start vs Next.js vs React Router / Remix -toc: false ---- - -Before you commit to a new tool, it's always nice to know how it stacks up against the competition! - -> This comparison table strives to be as accurate and as unbiased as possible. If you use any of these libraries and feel the information could be improved, feel free to suggest changes (with notes or evidence of claims) using the "Edit this page on GitHub" link at the bottom of this page. - -Feature/Capability Key: - -- βœ… 1st-class, built-in, and ready to use with no added configuration or code -- 🟑 Partial Support (on a scale of 5) -- 🟠 Supported via addon/community package -- πŸ”Ά Possible, but requires custom code/implementation/casting -- πŸ›‘ Not officially supported - -| | TanStack Router / Start | React Router DOM [_(Website)_][router] | Next.JS [_(Website)_][nextjs] | -| ---------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------- | ----------------------------------------------------- | -| Github Repo / Stars | [![][stars-tanstack-router]][gh-tanstack-router] | [![][stars-router]][gh-router] | [![][stars-nextjs]][gh-nextjs] | -| Bundle Size | [![][bp-tanstack-router]][bpl-tanstack-router] | [![][bp-router]][bpl-router] | ❓ | -| History, Memory & Hash Routers | βœ… | βœ… | πŸ›‘ | -| Nested / Layout Routes | βœ… | βœ… | 🟑 | -| Suspense-like Route Transitions | βœ… | βœ… | βœ… | -| Typesafe Routes | βœ… | 🟑 (1/5) | 🟑 | -| Code-based Routes | βœ… | βœ… | πŸ›‘ | -| File-based Routes | βœ… | βœ… | βœ… | -| Virtual/Programmatic File-based Routes | βœ… | βœ… | πŸ›‘ | -| Router Loaders | βœ… | βœ… | βœ… | -| SWR Loader Caching | βœ… | πŸ›‘ | βœ… | -| Route Prefetching | βœ… | βœ… | βœ… | -| Auto Route Prefetching | βœ… | βœ… | βœ… | -| Route Prefetching Delay | βœ… | πŸ”Ά | πŸ›‘ | -| Path Params | βœ… | βœ… | βœ… | -| Typesafe Path Params | βœ… | βœ… | πŸ›‘ | -| Typesafe Route Context | βœ… | πŸ›‘ | πŸ›‘ | -| Path Param Validation | βœ… | πŸ›‘ | πŸ›‘ | -| Custom Path Param Parsing/Serialization | βœ… | πŸ›‘ | πŸ›‘ | -| Ranked Routes | βœ… | βœ… | βœ… | -| Active Link Customization | βœ… | βœ… | βœ… | -| Optimistic UI | βœ… | βœ… | πŸ”Ά | -| Typesafe Absolute + Relative Navigation | βœ… | 🟑 (1/5 via `buildHref` util) | 🟠 (IDE plugin) | -| Route Mount/Transition/Unmount Events | βœ… | πŸ›‘ | πŸ›‘ | -| Devtools | βœ… | 🟠 | πŸ›‘ | -| Basic Search Params | βœ… | βœ… | βœ… | -| Search Param Hooks | βœ… | βœ… | βœ… | -| ``/`useNavigate` Search Param API | βœ… | 🟑 (search-string only via the `to`/`search` options) | 🟑 (search-string only via the `to`/`search` options) | -| JSON Search Params | βœ… | πŸ”Ά | πŸ”Ά | -| TypeSafe Search Params | βœ… | πŸ›‘ | πŸ›‘ | -| Search Param Schema Validation | βœ… | πŸ›‘ | πŸ›‘ | -| Search Param Immutability + Structural Sharing | βœ… | πŸ”Ά | πŸ›‘ | -| Custom Search Param parsing/serialization | βœ… | πŸ”Ά | πŸ›‘ | -| Search Param Middleware | βœ… | πŸ›‘ | πŸ›‘ | -| Suspense Route Elements | βœ… | βœ… | βœ… | -| Route Error Elements | βœ… | βœ… | βœ… | -| Route Pending Elements | βœ… | βœ… | βœ… | -| ``/`useBlocker` | βœ… | πŸ”Ά (no hard reloads or cross-origin navigation) | πŸ›‘ | -| Deferred Primitives | βœ… | βœ… | βœ… | -| Navigation Scroll Restoration | βœ… | βœ… | ❓ | -| ElementScroll Restoration | βœ… | πŸ›‘ | πŸ›‘ | -| Async Scroll Restoration | βœ… | πŸ›‘ | πŸ›‘ | -| Router Invalidation | βœ… | βœ… | βœ… | -| Runtime Route Manipulation (Fog of War) | πŸ›‘ | βœ… | βœ… | -| Parallel Routes | πŸ›‘ | πŸ›‘ | βœ… | -| -- | -- | -- | -- | -| **Full Stack** | -- | -- | -- | -| SSR | βœ… | βœ… | βœ… | -| Streaming SSR | βœ… | βœ… | βœ… | -| Generic RPCs | βœ… | πŸ›‘ | πŸ›‘ | -| Generic RPC Middleware | βœ… | πŸ›‘ | πŸ›‘ | -| React Server Functions | βœ… | πŸ›‘ | βœ… | -| React Server Function Middleware | βœ… | πŸ›‘ | πŸ›‘ | -| API Routes | βœ… | βœ… | βœ… | -| API Middleware | βœ… | βœ… | βœ… | -| React Server Components | πŸ›‘ | 🟑 (Experimental) | βœ… | -| `
` API | πŸ›‘ | βœ… | βœ… | - -[bp-tanstack-router]: https://badgen.net/bundlephobia/minzip/@tanstack/react-router -[bpl-tanstack-router]: https://bundlephobia.com/result?p=@tanstack/react-router -[gh-tanstack-router]: https://github.com/tanstack/router -[stars-tanstack-router]: https://img.shields.io/github/stars/tanstack/router?label=%F0%9F%8C%9F -[_]: _ -[router]: https://github.com/remix-run/react-router -[bp-router]: https://badgen.net/bundlephobia/minzip/react-router -[gh-router]: https://github.com/remix-run/react-router -[stars-router]: https://img.shields.io/github/stars/remix-run/react-router?label=%F0%9F%8C%9F -[bpl-router]: https://bundlephobia.com/result?p=react-router -[bpl-history]: https://bundlephobia.com/result?p=history -[_]: _ -[nextjs]: https://nextjs.org/docs/routing/introduction -[bp-nextjs]: https://badgen.net/bundlephobia/minzip/next.js?label=All -[gh-nextjs]: https://github.com/vercel/next.js -[stars-nextjs]: https://img.shields.io/github/stars/vercel/next.js?label=%F0%9F%8C%9F -[bpl-nextjs]: https://bundlephobia.com/result?p=next diff --git a/docs/router/framework/react/faq.md b/docs/router/framework/react/faq.md index 4bed5d4a64b..f66ffca03c0 100644 --- a/docs/router/framework/react/faq.md +++ b/docs/router/framework/react/faq.md @@ -4,6 +4,20 @@ title: Frequently Asked Questions Welcome to the TanStack Router FAQ! Here you'll find answers to common questions about the TanStack Router. If you have a question that isn't answered here, please feel free to ask in the [TanStack Discord](https://tlinz.com/discord). +## Why should you choose TanStack Router over another router? + +To answer this question, it's important to view the other options in the space. There are many alternatives to choose from, but only a couple that are widely adopted and actively maintained: + +- **Next.js** - Widely regarded as the leading framework for starting new React projects. Its design focuses on performance, development workflows, and cutting-edge technology. The framework's APIs and abstractions, while powerful, can sometimes present as non-standard. Rapid growth and industry adoption have resulted in a feature-rich experience, sometimes leading to a steeper learning curve and increased overhead. +- **Remix / React Router** - Based on the historically successful React Router, Remix delivers a powerful developer and user experience. Its API and architectural vision are firmly rooted in web standards such as Request/Response, with an emphasis on adaptability across various JavaScript environments. Many of its APIs and abstractions are well-designed and have influenced more than a few of TanStack Router's APIs. However, its rigid design, the integration of type safety as an add-on, and sometimes strict adherence to platform APIs can present limitations for some developers. + +These frameworks and routers have their strengths, but they also come with trade-offs that may not align with every project's needs. TanStack Router aims to strike a balance by offering routing APIs designed to improve the developer experience without sacrificing flexibility or performance. + +## Is TanStack Router a framework? + +TanStack Router itself is not a "framework" in the traditional sense, since it doesn't address a few other common full-stack concerns. However, TanStack Router has been designed to be upgradable to a full-stack framework when used in conjunction with other tools that address bundling, deployments, and server-side-specific functionality. This is why we are currently developing [TanStack Start](https://tanstack.com/start), a full-stack framework that is built on top of TanStack Router and Vite. +For a deeper dive on the history of TanStack Router, feel free to read [TanStack Router's History](../decisions-on-dx.md#tanstack-routers-origin-story). + ## Should I commit my `routeTree.gen.ts` file into git? Yes! Although the route tree file (i.e., `routeTree.gen.ts`) is generated by TanStack Router, it is essentially part of your application’s runtime, not a build artifact. The route tree file is a critical part of your application’s source code, and it is used by TanStack Router to build your application’s routes at runtime. diff --git a/docs/router/framework/react/installation.md b/docs/router/framework/react/installation.md deleted file mode 100644 index 023eb807314..00000000000 --- a/docs/router/framework/react/installation.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Installation ---- - -> **Quick Installation**: For step-by-step installation instructions, see our [How to Install TanStack Router](./how-to/install.md) guide. - -You can install TanStack Router with any [NPM](https://npmjs.com) package manager. - -```sh -npm install @tanstack/react-router -# or -pnpm add @tanstack/react-router -# or -yarn add @tanstack/react-router -# or -bun add @tanstack/react-router -# or -deno add npm:@tanstack/react-router -``` - -TanStack Router is currently only compatible with React (with ReactDOM) and Solid. If you would like to contribute to the React Native, Angular, or Vue adapter, please reach out to us on [Discord](https://tlinz.com/discord). - -### Requirements - -[//]: # 'Requirements' - -- `react` either v18.x.x or v19.x.x -- `react-dom`, either v18.x.x or v19.x.x - - Note that `ReactDOM.createRoot` is required. - - The legacy `.render()` function is not supported. - -[//]: # 'Requirements' - -TypeScript is _optional_, but **HIGHLY** recommended! If you are using it, please ensure you are using `typescript>=v5.3.x`. - -> [!IMPORTANT] -> We aim to support the last five minor versions of TypeScript. If you are using an older version, you may run into issues. Please upgrade to the latest version of TypeScript to ensure compatibility. We may drop support for older versions of TypeScript, outside of the range mentioned above, without warning in a minor or patch release. - -### LLM Assistance Support - -All of our documentation for TanStack React Router is integrated into the NPM module and can be easily installed as LLM rules. You can integrate LLM rules into the editor of your choice using [vibe-rules](https://www.npmjs.com/package/vibe-rules). - -```bash -pnpm add -g vibe-rules -``` - -Then run `vibe-rules` with the editor of your choice. Here is an example for Cursor: - -```bash -vibe-rules install cursor -``` - -But you can also use `windsurf`, `claude-code`, etc. Check the [vibe-rules](https://www.npmjs.com/package/vibe-rules) documentation for more information. - -### Usage with yarn workspaces - -When using yarn workspaces, you will need to add the following config to the `.yarnrc.yml` of the application using TanStack Router - -```yml -pnpFallbackMode: all -pnpMode: loose -``` diff --git a/docs/router/framework/react/installation/manual.md b/docs/router/framework/react/installation/manual.md new file mode 100644 index 00000000000..2ba7002c4c0 --- /dev/null +++ b/docs/router/framework/react/installation/manual.md @@ -0,0 +1,231 @@ +--- +title: Manual Setup +--- + +To set up TanStack Router manually in a React project, follow the steps below. This gives you a bare minimum setup to get going with TanStack Router using both file-based route generation and code-based route configuration: + +## Using File-Based Route Generation + +#### Install TanStack Router, Vite Plugin, and the Router Devtools + +```sh +npm install @tanstack/react-router @tanstack/react-router-devtools +npm install -D @tanstack/router-plugin +# or +pnpm add @tanstack/react-router @tanstack/react-router-devtools +pnpm add -D @tanstack/router-plugin +# or +yarn add @tanstack/react-router @tanstack/react-router-devtools +yarn add -D @tanstack/router-plugin +# or +bun add @tanstack/react-router @tanstack/react-router-devtools +bun add -D @tanstack/router-plugin +# or +deno add npm:@tanstack/react-router npm:@tanstack/router-plugin npm:@tanstack/react-router-devtools +``` + +#### Configure the Vite Plugin + +```tsx +// vite.config.ts +import { defineConfig } from 'vite' +import react from '@vitejs/plugin-react' +import { tanstackRouter } from '@tanstack/router-plugin/vite' + +// https://vitejs.dev/config/ +export default defineConfig({ + plugins: [ + // Please make sure that '@tanstack/router-plugin' is passed before '@vitejs/plugin-react' + tanstackRouter({ + target: 'react', + autoCodeSplitting: true, + }), + react(), + // ..., + ], +}) +``` + +> [!TIP] +> If you are not using Vite, or any of the supported bundlers, you can check out the [TanStack Router CLI](../with-router-cli) guide for more info. + +Create the following files: + +- `src/routes/__root.tsx` (with two '`_`' characters) +- `src/routes/index.tsx` +- `src/routes/about.tsx` +- `src/main.tsx` + +#### `src/routes/__root.tsx` + +```tsx +import { createRootRoute, Link, Outlet } from '@tanstack/react-router' +import { TanStackRouterDevtools } from '@tanstack/react-router-devtools' + +const RootLayout = () => ( + <> +
+ + Home + {' '} + + About + +
+
+ + + +) + +export const Route = createRootRoute({ component: RootLayout }) +``` + +#### `src/routes/index.tsx` + +```tsx +import { createFileRoute } from '@tanstack/react-router' + +export const Route = createFileRoute('/')({ + component: Index, +}) + +function Index() { + return ( +
+

Welcome Home!

+
+ ) +} +``` + +#### `src/routes/about.tsx` + +```tsx +import { createFileRoute } from '@tanstack/react-router' + +export const Route = createFileRoute('/about')({ + component: About, +}) + +function About() { + return
Hello from About!
+} +``` + +#### `src/main.tsx` + +Regardless of whether you are using the `@tanstack/router-plugin` package and running the `npm run dev`/`npm run build` scripts, or manually running the `tsr watch`/`tsr generate` commands from your package scripts, the route tree file will be generated at `src/routeTree.gen.ts`. + +Import the generated route tree and create a new router instance: + +```tsx +import { StrictMode } from 'react' +import ReactDOM from 'react-dom/client' +import { RouterProvider, createRouter } from '@tanstack/react-router' + +// Import the generated route tree +import { routeTree } from './routeTree.gen' + +// Create a new router instance +const router = createRouter({ routeTree }) + +// Register the router instance for type safety +declare module '@tanstack/react-router' { + interface Register { + router: typeof router + } +} + +// Render the app +const rootElement = document.getElementById('root')! +if (!rootElement.innerHTML) { + const root = ReactDOM.createRoot(rootElement) + root.render( + + + , + ) +} +``` + +If you are working with this pattern you should change the `id` of the root `
` on your `index.html` file to `
` + +## Using Code-Based Route Configuration + +> [!IMPORTANT] +> The following example shows how to configure routes using code, and for simplicity's sake is in a single file for this demo. While code-based generation allows you to declare many routes and even the router instance in a single file, we recommend splitting your routes into separate files for better organization and performance as your application grows. + +```tsx +import { StrictMode } from 'react' +import ReactDOM from 'react-dom/client' +import { + Outlet, + RouterProvider, + Link, + createRouter, + createRoute, + createRootRoute, +} from '@tanstack/react-router' +import { TanStackRouterDevtools } from '@tanstack/react-router-devtools' + +const rootRoute = createRootRoute({ + component: () => ( + <> +
+ + Home + {' '} + + About + +
+
+ + + + ), +}) + +const indexRoute = createRoute({ + getParentRoute: () => rootRoute, + path: '/', + component: function Index() { + return ( +
+

Welcome Home!

+
+ ) + }, +}) + +const aboutRoute = createRoute({ + getParentRoute: () => rootRoute, + path: '/about', + component: function About() { + return
Hello from About!
+ }, +}) + +const routeTree = rootRoute.addChildren([indexRoute, aboutRoute]) + +const router = createRouter({ routeTree }) + +declare module '@tanstack/react-router' { + interface Register { + router: typeof router + } +} + +const rootElement = document.getElementById('app')! +if (!rootElement.innerHTML) { + const root = ReactDOM.createRoot(rootElement) + root.render( + + + , + ) +} +``` + +If you glossed over these examples or didn't understand something, we don't blame you, because there's so much more to learn to really take advantage of TanStack Router! Let's move on. diff --git a/docs/router/framework/react/migrate-from-react-location.md b/docs/router/framework/react/installation/migrate-from-react-location.md similarity index 100% rename from docs/router/framework/react/migrate-from-react-location.md rename to docs/router/framework/react/installation/migrate-from-react-location.md diff --git a/docs/router/framework/react/migrate-from-react-router.md b/docs/router/framework/react/installation/migrate-from-react-router.md similarity index 100% rename from docs/router/framework/react/migrate-from-react-router.md rename to docs/router/framework/react/installation/migrate-from-react-router.md diff --git a/docs/router/framework/react/routing/installation-with-esbuild.md b/docs/router/framework/react/installation/with-esbuild.md similarity index 100% rename from docs/router/framework/react/routing/installation-with-esbuild.md rename to docs/router/framework/react/installation/with-esbuild.md diff --git a/docs/router/framework/react/routing/installation-with-router-cli.md b/docs/router/framework/react/installation/with-router-cli.md similarity index 100% rename from docs/router/framework/react/routing/installation-with-router-cli.md rename to docs/router/framework/react/installation/with-router-cli.md diff --git a/docs/router/framework/react/routing/installation-with-rspack.md b/docs/router/framework/react/installation/with-rspack.md similarity index 100% rename from docs/router/framework/react/routing/installation-with-rspack.md rename to docs/router/framework/react/installation/with-rspack.md diff --git a/docs/router/framework/react/routing/installation-with-vite.md b/docs/router/framework/react/installation/with-vite.md similarity index 100% rename from docs/router/framework/react/routing/installation-with-vite.md rename to docs/router/framework/react/installation/with-vite.md diff --git a/docs/router/framework/react/routing/installation-with-webpack.md b/docs/router/framework/react/installation/with-webpack.md similarity index 100% rename from docs/router/framework/react/routing/installation-with-webpack.md rename to docs/router/framework/react/installation/with-webpack.md diff --git a/docs/router/framework/react/quick-start.md b/docs/router/framework/react/quick-start.md index 37cd2449c44..85c009cd8bf 100644 --- a/docs/router/framework/react/quick-start.md +++ b/docs/router/framework/react/quick-start.md @@ -1,245 +1,138 @@ --- +id: quick-start title: Quick Start --- -If you're feeling impatient and prefer to skip all of our wonderful documentation, here is the bare minimum to get going with TanStack Router using both file-based route generation and code-based route configuration: +TanStack Router can be quickly added to any existing React project or used to scaffold a new one. -## Using File-Based Route Generation +## TanStack Router Installation -File based route generation (through Vite, and other supported bundlers) is the recommended way to use TanStack Router as it provides the best experience, performance, and ergonomics for the least amount of effort. +### Requirements -### Scaffolding Your First TanStack Router Project +Before installing TanStack router, please ensure your project meets the following requirements: -```sh -npx create-tsrouter-app@latest my-app --template file-router -``` +[//]: # 'Requirements' + +- `react` v18 or later with `createRoot` support. +- `react-dom` v18 or later. + +[//]: # 'Requirements' + +> [!NOTE] Using TypeScript (`v5.3.x or higher`) is recommended for the best development experience, though not strictly required. We aim to support the last 5 minor versions of TypeScript, but using the latest version will help avoid potential issues. -See [create-tsrouter-app](https://github.com/TanStack/create-tsrouter-app/tree/main/cli/create-tsrouter-app) for more options. +TanStack Router is currently only compatible with React (with ReactDOM) and Solid. If you're interested in contributing to support other frameworks, such as React Native, Angular, or Vue, please reach out to us on [Discord](https://tlinz.com/discord). -### Manual Setup +### Download and Install -Alternatively, you can manually setup the project using the following steps: +To install TanStack Router in your project, run the following command using your preferred package manager: -#### Install TanStack Router, Vite Plugin, and the Router Devtools +[//]: # 'installCommand' ```sh -npm install @tanstack/react-router @tanstack/react-router-devtools -npm install -D @tanstack/router-plugin +npm install @tanstack/router # or -pnpm add @tanstack/react-router @tanstack/react-router-devtools -pnpm add -D @tanstack/router-plugin +pnpm add @tanstack/router +#or +yarn add @tanstack/router # or -yarn add @tanstack/react-router @tanstack/react-router-devtools -yarn add -D @tanstack/router-plugin +bun add @tanstack/router # or -bun add @tanstack/react-router @tanstack/react-router-devtools -bun add -D @tanstack/router-plugin -# or -deno add npm:@tanstack/react-router npm:@tanstack/router-plugin npm:@tanstack/react-router-devtools +deno add npm:@tanstack/router ``` -#### Configure the Vite Plugin - -```tsx -// vite.config.ts -import { defineConfig } from 'vite' -import react from '@vitejs/plugin-react' -import { tanstackRouter } from '@tanstack/router-plugin/vite' - -// https://vitejs.dev/config/ -export default defineConfig({ - plugins: [ - // Please make sure that '@tanstack/router-plugin' is passed before '@vitejs/plugin-react' - tanstackRouter({ - target: 'react', - autoCodeSplitting: true, - }), - react(), - // ..., - ], -}) -``` +[//]: # 'installCommand' + +Once installed, you can verify the installation by checking your `package.json` file for the `@tanstack/router` dependency. -> [!TIP] -> If you are not using Vite, or any of the supported bundlers, you can check out the [TanStack Router CLI](../routing/installation-with-router-cli.md) guide for more info. - -Create the following files: - -- `src/routes/__root.tsx` (with two '`_`' characters) -- `src/routes/index.tsx` -- `src/routes/about.tsx` -- `src/main.tsx` - -#### `src/routes/__root.tsx` - -```tsx -import { createRootRoute, Link, Outlet } from '@tanstack/react-router' -import { TanStackRouterDevtools } from '@tanstack/react-router-devtools' - -const RootLayout = () => ( - <> -
- - Home - {' '} - - About - -
-
- - - -) - -export const Route = createRootRoute({ component: RootLayout }) +[//]: # 'packageJson' + +```json +{ + "dependencies": { + "@tanstack/react-router": "^x.x.x" + } +} ``` -#### `src/routes/index.tsx` +[//]: # 'packageJson' -```tsx -import { createFileRoute } from '@tanstack/react-router' +## New Project Setup -export const Route = createFileRoute('/')({ - component: Index, -}) +To quickly scaffold a new project with TanStack Router, you can use the `create-tsrouter-app` command-line tool. This tool sets up a new React application with TanStack Router pre-configured, allowing you to get started quickly. -function Index() { - return ( -
-

Welcome Home!

-
- ) -} +> [!TIP] For full details on available options and templates, visit the [`create-tsrouter-app` documentation](https://github.com/TanStack/create-tsrouter-app/tree/main/cli/create-tsrouter-app). + +To create a new project, run the following command in your terminal: + +[//]: # 'createAppCommand' + +```sh +npx create-tsrouter-app@latest ``` -#### `src/routes/about.tsx` +[//]: # 'createAppCommand' -```tsx -import { createFileRoute } from '@tanstack/react-router' +The CLI will guide you through a short series of prompts to customize your setup, including options for: -export const Route = createFileRoute('/about')({ - component: About, -}) +[//]: # 'CLIPrompts' -function About() { - return
Hello from About!
-} +- File-based or code-based route configuration +- TypeScript support +- Tailwind CSS integration +- Toolchain setup +- Git initialization + +[//]: # 'CLIPrompts' + +Once complete, a new React project will be generated with TanStack Router installed and ready to use. All dependencies are automatically installed, so you can jump straight into development: + +```sh +cd your-project-name +npm run dev ``` -#### `src/main.tsx` +### Routing Options -Regardless of whether you are using the `@tanstack/router-plugin` package and running the `npm run dev`/`npm run build` scripts, or manually running the `tsr watch`/`tsr generate` commands from your package scripts, the route tree file will be generated at `src/routeTree.gen.ts`. +TanStack Router supports both file-based and code-based route configurations, allowing you to choose the approach that best fits your workflow. -Import the generated route tree and create a new router instance: +#### File-Based Route Generation -```tsx -import { StrictMode } from 'react' -import ReactDOM from 'react-dom/client' -import { RouterProvider, createRouter } from '@tanstack/react-router' +The file-based approach is the recommended option for most projects. It automatically creates routes based on your file structure, giving you the best mix of performance, simplicity, and developer experience. -// Import the generated route tree -import { routeTree } from './routeTree.gen' +To create a new project using file-based route generation, run the following command: -// Create a new router instance -const router = createRouter({ routeTree }) +[//]: # 'createAppCommandFileBased' -// Register the router instance for type safety -declare module '@tanstack/react-router' { - interface Register { - router: typeof router - } -} +```sh +npx create-tsrouter-app@latest my-app --template file-router +``` -// Render the app -const rootElement = document.getElementById('root')! -if (!rootElement.innerHTML) { - const root = ReactDOM.createRoot(rootElement) - root.render( - - - , - ) -} +[//]: # 'createAppCommandFileBased' + +This command sets up a new directory called `my-app` with everything configured. Once setup completes, you can then start your development server and begin building your application: + +```sh +cd my-app +npm run dev ``` -If you are working with this pattern you should change the `id` of the root `
` on your `index.html` file to `
` - -## Using Code-Based Route Configuration - -> [!IMPORTANT] -> The following example shows how to configure routes using code, and for simplicity's sake is in a single file for this demo. While code-based generation allows you to declare many routes and even the router instance in a single file, we recommend splitting your routes into separate files for better organization and performance as your application grows. - -```tsx -import { StrictMode } from 'react' -import ReactDOM from 'react-dom/client' -import { - Outlet, - RouterProvider, - Link, - createRouter, - createRoute, - createRootRoute, -} from '@tanstack/react-router' -import { TanStackRouterDevtools } from '@tanstack/react-router-devtools' - -const rootRoute = createRootRoute({ - component: () => ( - <> -
- - Home - {' '} - - About - -
-
- - - - ), -}) - -const indexRoute = createRoute({ - getParentRoute: () => rootRoute, - path: '/', - component: function Index() { - return ( -
-

Welcome Home!

-
- ) - }, -}) - -const aboutRoute = createRoute({ - getParentRoute: () => rootRoute, - path: '/about', - component: function About() { - return
Hello from About!
- }, -}) - -const routeTree = rootRoute.addChildren([indexRoute, aboutRoute]) - -const router = createRouter({ routeTree }) - -declare module '@tanstack/react-router' { - interface Register { - router: typeof router - } -} +#### Code-Based Route Configuration -const rootElement = document.getElementById('app')! -if (!rootElement.innerHTML) { - const root = ReactDOM.createRoot(rootElement) - root.render( - - - , - ) -} +If you prefer to define routes programmatically, you can use the code-based route configuration. This approach gives you full control over routing logic while maintaining the same project scaffolding workflow. + +[//]: # 'createAppCommandCodeBased' + +```sh +npx create-tsrouter-app@latest my-app +``` + +[//]: # 'createAppCommandCodeBased' + +Similar to the file-based setup, this command creates a new directory called `my-app` with TanStack Router configured for code-based routing. After setup, navigate to your project directory and start the development server: + +```sh +cd my-app +npm run dev ``` -If you glossed over these examples or didn't understand something, we don't blame you, because there's so much more to learn to really take advantage of TanStack Router! Let's move on. +With either approach, you can now start building your React application with TanStack Router! diff --git a/docs/router/framework/react/routing/file-based-routing.md b/docs/router/framework/react/routing/file-based-routing.md index 99d22d1cfb5..03288f5948c 100644 --- a/docs/router/framework/react/routing/file-based-routing.md +++ b/docs/router/framework/react/routing/file-based-routing.md @@ -113,13 +113,13 @@ To enable file-based routing, you'll need to be using React with a supported bun [//]: # 'SupportedBundlersList' -- [Installation with Vite](../installation-with-vite.md) -- [Installation with Rspack/Rsbuild](../installation-with-rspack.md) -- [Installation with Webpack](../installation-with-webpack.md) -- [Installation with Esbuild](../installation-with-esbuild.md) +- [Installation with Vite](../../installation/with-vite) +- [Installation with Rspack/Rsbuild](../../installation/with-rspack) +- [Installation with Webpack](../../installation/with-webpack) +- [Installation with Esbuild](../../installation/with-esbuild) [//]: # 'SupportedBundlersList' When using TanStack Router's file-based routing through one of the supported bundlers, our plugin will **automatically generate your route configuration through your bundler's dev and build processes**. It is the easiest way to use TanStack Router's route generation features. -If your bundler is not yet supported, you can reach out to us on Discord or GitHub to let us know. Till then, fear not! You can still use the [`@tanstack/router-cli`](../installation-with-router-cli.md) package to generate your route tree file. +If your bundler is not yet supported, you can reach out to us on Discord or GitHub to let us know. diff --git a/docs/router/framework/solid/installation.md b/docs/router/framework/solid/installation/manual.md similarity index 61% rename from docs/router/framework/solid/installation.md rename to docs/router/framework/solid/installation/manual.md index 3d2de60570e..0624eac8f3e 100644 --- a/docs/router/framework/solid/installation.md +++ b/docs/router/framework/solid/installation/manual.md @@ -1,6 +1,6 @@ --- -title: Installation -ref: docs/router/framework/react/installation.md +title: Manual Setup +ref: docs/router/framework/react/installation/manual.md replace: { 'react-router': 'solid-router' } --- diff --git a/docs/router/framework/solid/quick-start.md b/docs/router/framework/solid/quick-start.md index 287c31d8c57..3121ab85d41 100644 --- a/docs/router/framework/solid/quick-start.md +++ b/docs/router/framework/solid/quick-start.md @@ -1,232 +1,65 @@ --- -title: Quick Start +ref: docs/router/framework/react/quick-start.md +replace: { 'React': 'Solid' } --- -If you're feeling impatient and prefer to skip all of our wonderful documentation, here is the bare minimum to get going with TanStack Router using both file-based route generation and code-based route configuration: +[//]: # 'Requirements' -## Using File-Based Route Generation +- `solid-js`v1.x.x -File based route generation (through Vite, and other supported bundlers) is the recommended way to use TanStack Router as it provides the best experience, performance, and ergonomics for the least amount of effort. - -### Scaffolding Your First TanStack Router Project +[//]: # 'Requirements' +[//]: # 'installCommand' ```sh -npx create-tsrouter-app@latest my-app --framework solid --template file-router -``` - -See [create-tsrouter-app](https://github.com/TanStack/create-tsrouter-app/tree/main/cli/create-tsrouter-app) for more options. - -### Manual Setup - -Alternatively, you can manually setup the project using the following steps: - -#### Install TanStack Router, Vite Plugin, and the Router Devtools - -```sh -npm install @tanstack/solid-router @tanstack/solid-router-devtools -npm install -D @tanstack/router-plugin -# or -pnpm add @tanstack/solid-router @tanstack/solid-router-devtools -pnpm add -D @tanstack/router-plugin +npm install @tanstack/solid-router # or -yarn add @tanstack/solid-router @tanstack/solid-router-devtools -yarn add -D @tanstack/router-plugin +pnpm add @tanstack/solid-router +#or +yarn add @tanstack/solid-router # or -bun add @tanstack/solid-router @tanstack/solid-router-devtools -bun add -D @tanstack/router-plugin +bun add @tanstack/solid-router # or -deno add npm:@tanstack/solid-router npm:@tanstack/router-plugin npm:@tanstack/solid-router-devtools +deno add npm:@tanstack/solid-router ``` -#### Configure the Vite Plugin - -```tsx -// vite.config.ts -import { defineConfig } from 'vite' -import solid from 'vite-plugin-solid' -import { tanstackRouter } from '@tanstack/router-plugin/vite' - -// https://vitejs.dev/config/ -export default defineConfig({ - plugins: [ - tanstackRouter({ - target: 'solid', - autoCodeSplitting: true, - }), - solid(), - // ..., - ], -}) -``` +[//]: # 'installCommand' +[//]: # 'packageJson' -> [!TIP] -> If you are not using Vite, or any of the supported bundlers, you can check out the [TanStack Router CLI](../routing/installation-with-router-cli.md) guide for more info. - -Create the following files: - -- `src/routes/__root.tsx` -- `src/routes/index.tsx` -- `src/routes/about.tsx` -- `src/main.tsx` - -#### `src/routes/__root.tsx` - -```tsx -import { createRootRoute, Link, Outlet } from '@tanstack/solid-router' -import { TanStackRouterDevtools } from '@tanstack/solid-router-devtools' - -export const Route = createRootRoute({ - component: () => ( - <> -
- - Home - {' '} - - About - -
-
- - - - ), -}) -``` - -#### `src/routes/index.tsx` - -```tsx -import { createFileRoute } from '@tanstack/solid-router' - -export const Route = createFileRoute('/')({ - component: Index, -}) - -function Index() { - return ( -
-

Welcome Home!

-
- ) +```json +{ + "dependencies": { + "@tanstack/solid-router": "^x.x.x" + } } ``` -#### `src/routes/about.tsx` - -```tsx -import { createFileRoute } from '@tanstack/solid-router' +[//]: # 'packageJson' +[//]: # 'createAppCommand' -export const Route = createFileRoute('/about')({ - component: About, -}) - -function About() { - return
Hello from About!
-} +```sh +npx create-tsrouter-app@latest --framework solid ``` -#### `src/main.tsx` - -Regardless of whether you are using the `@tanstack/router-plugin` package and running the `npm run dev`/`npm run build` scripts, or manually running the `tsr watch`/`tsr generate` commands from your package scripts, the route tree file will be generated at `src/routeTree.gen.ts`. +[//]: # 'createAppCommand' +[//]: # 'CLIPrompts' -Import the generated route tree and create a new router instance: +- File-based or code-based route configuration +- TypeScript support +- Toolchain setup +- Git initialization -```tsx -import { render } from 'solid-js/web' -import { RouterProvider, createRouter } from '@tanstack/solid-router' +[//]: # 'CLIPrompts' +[//]: # 'createAppCommandFileBased' -// Import the generated route tree -import { routeTree } from './routeTree.gen' - -// Create a new router instance -const router = createRouter({ routeTree }) - -// Register the router instance for type safety -declare module '@tanstack/solid-router' { - interface Register { - router: typeof router - } -} - -// Render the app -const rootElement = document.getElementById('root')! -if (!rootElement.innerHTML) { - render(() => , rootElement) -} +```sh +npx create-tsrouter-app@latest my-app --framework solid --template file-router ``` -If you are working with this pattern you should change the `id` of the root `
` on your `index.html` file to `
` - -## Using Code-Based Route Configuration +[//]: # 'createAppCommandFileBased' +[//]: # 'createAppCommandCodeBased' -> [!IMPORTANT] -> The following example shows how to configure routes using code, and for simplicity's sake is in a single file for this demo. While code-based generation allows you to declare many routes and even the router instance in a single file, we recommend splitting your routes into separate files for better organization and performance as your application grows. - -```tsx -import { render } from 'solid-js/web' -import { - Outlet, - RouterProvider, - Link, - createRouter, - createRoute, - createRootRoute, -} from '@tanstack/solid-router' -import { TanStackRouterDevtools } from '@tanstack/solid-router-devtools' - -const rootRoute = createRootRoute({ - component: () => ( - <> -
- - Home - {' '} - - About - -
-
- - - - ), -}) - -const indexRoute = createRoute({ - getParentRoute: () => rootRoute, - path: '/', - component: function Index() { - return ( -
-

Welcome Home!

-
- ) - }, -}) - -const aboutRoute = createRoute({ - getParentRoute: () => rootRoute, - path: '/about', - component: function About() { - return
Hello from About!
- }, -}) - -const routeTree = rootRoute.addChildren([indexRoute, aboutRoute]) - -const router = createRouter({ routeTree }) - -declare module '@tanstack/solid-router' { - interface Register { - router: typeof router - } -} - -const rootElement = document.getElementById('app')! -if (!rootElement.innerHTML) { - render(() => , rootElement) -} +```sh +npx create-tsrouter-app@latest my-app --framework solid ``` -If you glossed over these examples or didn't understand something, we don't blame you, because there's so much more to learn to really take advantage of TanStack Router! Let's move on. +[//]: # 'createAppCommandCodeBased' diff --git a/docs/router/framework/solid/routing/installation-with-router-cli.md b/docs/router/framework/solid/routing/installation-with-router-cli.md index fb493e368f0..11a88cb6d09 100644 --- a/docs/router/framework/solid/routing/installation-with-router-cli.md +++ b/docs/router/framework/solid/routing/installation-with-router-cli.md @@ -1,5 +1,5 @@ --- -ref: docs/router/framework/react/routing/installation-with-router-cli.md +ref: docs/router/framework/react/routing/installation/with-router-cli.md --- [//]: # 'AfterScripts' diff --git a/docs/router/framework/solid/routing/installation-with-vite.md b/docs/router/framework/solid/routing/installation-with-vite.md index 2f37aa3bd29..6f4abe25d15 100644 --- a/docs/router/framework/solid/routing/installation-with-vite.md +++ b/docs/router/framework/solid/routing/installation-with-vite.md @@ -1,5 +1,5 @@ --- -ref: docs/router/framework/react/routing/installation-with-vite.md +ref: docs/router/framework/react/routing/installation/with-vite.md --- [//]: # 'BundlerConfiguration' diff --git a/packages/router-cli/README.md b/packages/router-cli/README.md index 6f522c71d25..ee958166036 100644 --- a/packages/router-cli/README.md +++ b/packages/router-cli/README.md @@ -2,4 +2,4 @@ # TanStack Router CLI -See https://tanstack.com/router/latest/docs/framework/react/routing/installation-with-router-cli +See https://tanstack.com/router/latest/docs/framework/react/routing/installation/with-router-cli diff --git a/packages/router-plugin/README.md b/packages/router-plugin/README.md index 4aaa2834072..b3f04849158 100644 --- a/packages/router-plugin/README.md +++ b/packages/router-plugin/README.md @@ -10,4 +10,4 @@ See https://tanstack.com/router/latest/docs/framework/react/routing/file-based-r npm install -D @tanstack/router-plugin ``` -See https://tanstack.com/router/latest/docs/framework/react/routing/installation-with-router-cli for usage instructions. +See https://tanstack.com/router/latest/docs/framework/react/routing/installation/with-router-cli for usage instructions.