From f8777db77b0ac893e28510bbde424a30e5d406b4 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 18 Jul 2025 22:10:58 +0000 Subject: [PATCH 1/3] Add migration guide for React Router v6 to TanStack Router Co-authored-by: tannerlinsley --- docs/router/framework/react/how-to/README.md | 1 + .../react/how-to/deploy-to-production.md | 2 + .../react/how-to/migrate-from-react-router.md | 634 ++++++++++++++++++ how-to-guides-implementation-plan.md | 8 +- migration-guide-implementation-summary.md | 62 ++ 5 files changed, 704 insertions(+), 3 deletions(-) create mode 100644 docs/router/framework/react/how-to/migrate-from-react-router.md create mode 100644 migration-guide-implementation-summary.md diff --git a/docs/router/framework/react/how-to/README.md b/docs/router/framework/react/how-to/README.md index dabd163751..39f5c7ba0c 100644 --- a/docs/router/framework/react/how-to/README.md +++ b/docs/router/framework/react/how-to/README.md @@ -11,6 +11,7 @@ This directory contains focused, step-by-step instructions for common TanStack R - [Install TanStack Router](./install.md) - Basic installation steps - [Deploy to Production](./deploy-to-production.md) - Deploy your app to hosting platforms +- [Migrate from React Router v6](./migrate-from-react-router.md) - Complete migration guide from React Router v6 ## Using These Guides diff --git a/docs/router/framework/react/how-to/deploy-to-production.md b/docs/router/framework/react/how-to/deploy-to-production.md index a7c19b3557..eea0d6dc80 100644 --- a/docs/router/framework/react/how-to/deploy-to-production.md +++ b/docs/router/framework/react/how-to/deploy-to-production.md @@ -432,6 +432,8 @@ Before deploying, ensure you have: After deployment, you might want to: +- [Migrate from React Router v6](./migrate-from-react-router.md) - Complete migration guide if you're coming from React Router + + +### Advanced Features to Explore + +- **Route-based code splitting** - Improve performance with lazy loading +- **Search parameter validation** - Type-safe URL state management +- **Route preloading** - Enhance perceived performance +- **Route masking** - Advanced URL management +- **SSR setup** - Server-side rendering capabilities + +--- + +## Related Resources + +- [Migration from React Router (Basic Guide)](../migrate-from-react-router.md) - Original checklist-style guide +- [File-Based Routing Guide](../routing/file-based-routing.md) - Detailed routing concepts +- [Navigation Guide](../guide/navigation.md) - Complete navigation patterns +- [Search Parameters Guide](../guide/search-params.md) - Advanced search param usage +- [Type Safety Guide](../guide/type-safety.md) - TypeScript integration details +- [TanStack Router Comparison](../comparison.md) - Feature comparison with other routers \ No newline at end of file diff --git a/how-to-guides-implementation-plan.md b/how-to-guides-implementation-plan.md index 21300827ae..b4706792dc 100644 --- a/how-to-guides-implementation-plan.md +++ b/how-to-guides-implementation-plan.md @@ -5,7 +5,9 @@ This document outlines the multi-PR process for implementing the remaining how-t ## Progress Tracking - ✅ **Guide #1: Deploy to Production** - COMPLETED in docs/router/framework/react/how-to/deploy-to-production.md -- ⏳ **Guides #2-11** - Pending implementation +- ⏳ **Guide #2: Setup SSR** - IN PROGRESS (async task) +- ✅ **Guide #3: Migrate from React Router v6** - COMPLETED in docs/router/framework/react/how-to/migrate-from-react-router.md +- ⏳ **Guides #4-11** - Pending implementation ## Implementation Process @@ -197,8 +199,8 @@ Update this section as guides are completed: ``` ✅ Guide #1: Deploy to Production - COMPLETED -⏳ Guide #2: Setup SSR - IN PROGRESS -⏳ Guide #3: Migrate from React Router - PENDING +⏳ Guide #2: Setup SSR - IN PROGRESS (async task) +✅ Guide #3: Migrate from React Router - COMPLETED ⏳ Guide #4: Fix Build Issues - PENDING ⏳ Guide #5: Integrate UI Libraries - PENDING ⏳ Guide #6: Setup Authentication - PENDING diff --git a/migration-guide-implementation-summary.md b/migration-guide-implementation-summary.md new file mode 100644 index 0000000000..9c52a0c064 --- /dev/null +++ b/migration-guide-implementation-summary.md @@ -0,0 +1,62 @@ +# Migration Guide Implementation Summary + +## What Was Accomplished + +Successfully implemented **Guide #3: How to Migrate from React Router v6** as the next highest priority how-to guide (excluding setup-ssr which is being handled async). + +### Files Created/Updated + +1. **Created comprehensive migration guide**: `docs/router/framework/react/how-to/migrate-from-react-router.md` + - Complete step-by-step migration process (8 detailed steps) + - Production checklist with testing guidance + - Common problems section with solutions + - Cross-references to related documentation + +2. **Updated project documentation**: + - Added guide to `docs/router/framework/react/how-to/README.md` + - Updated tracking in `how-to-guides-implementation-plan.md` + - Added cross-reference from `deploy-to-production.md` + +### Guide Features + +The migration guide follows the established pattern and includes: + +- **Quick Start section** - Time requirements, difficulty, prerequisites +- **8-step detailed process** - From preparation to type safety +- **Production checklist** - Router config, migration, navigation, cleanup, testing +- **Common Problems** - 6 major issues with detailed solutions +- **Common Next Steps** - Advanced features to explore (commented until guides exist) +- **Related Resources** - Specific links to relevant documentation + +### Content Quality + +- **Copy-paste ready code examples** for all migration steps +- **Before/after comparisons** showing React Router v6 vs TanStack Router syntax +- **Real-world scenarios** covering nested routes, dynamic params, search params +- **TypeScript integration** with type safety guidance +- **Troubleshooting focus** addressing actual migration pain points + +## Next Priority Guidelines + +Based on the top-10 how-to guides priority list, the next highest priorities should be: + +1. **Guide #4: How to Fix Common Build and Bundler Issues** (if SSR guide still in progress) +2. **Guide #5: How to Integrate with Popular UI Libraries** +3. **Guide #6: How to Set Up Authentication and Protected Routes** + +### Implementation Notes + +- Each guide should follow the established pattern from deploy-to-production.md +- Cross-reference between guides as they become available +- Focus on practical, copy-paste ready solutions +- Address real GitHub issues and pain points mentioned in the priority analysis + +## Impact + +This migration guide addresses: +- **High priority user need** - Large React Router v6 user base requiring migration +- **Real developer pain points** - API differences, breaking changes, component refactoring +- **Productivity improvement** - Reduces migration friction from hours/days to 2-4 hours +- **Type safety benefits** - Guides users to TanStack Router's superior TypeScript experience + +The guide is positioned to significantly reduce migration support requests and improve developer adoption of TanStack Router. \ No newline at end of file From de08e2c92295844b023fa8410e79fb019d6753d8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 18 Jul 2025 22:19:11 +0000 Subject: [PATCH 2/3] Remove migration guide implementation summary document Co-authored-by: tannerlinsley --- migration-guide-implementation-summary.md | 62 ----------------------- 1 file changed, 62 deletions(-) delete mode 100644 migration-guide-implementation-summary.md diff --git a/migration-guide-implementation-summary.md b/migration-guide-implementation-summary.md deleted file mode 100644 index 9c52a0c064..0000000000 --- a/migration-guide-implementation-summary.md +++ /dev/null @@ -1,62 +0,0 @@ -# Migration Guide Implementation Summary - -## What Was Accomplished - -Successfully implemented **Guide #3: How to Migrate from React Router v6** as the next highest priority how-to guide (excluding setup-ssr which is being handled async). - -### Files Created/Updated - -1. **Created comprehensive migration guide**: `docs/router/framework/react/how-to/migrate-from-react-router.md` - - Complete step-by-step migration process (8 detailed steps) - - Production checklist with testing guidance - - Common problems section with solutions - - Cross-references to related documentation - -2. **Updated project documentation**: - - Added guide to `docs/router/framework/react/how-to/README.md` - - Updated tracking in `how-to-guides-implementation-plan.md` - - Added cross-reference from `deploy-to-production.md` - -### Guide Features - -The migration guide follows the established pattern and includes: - -- **Quick Start section** - Time requirements, difficulty, prerequisites -- **8-step detailed process** - From preparation to type safety -- **Production checklist** - Router config, migration, navigation, cleanup, testing -- **Common Problems** - 6 major issues with detailed solutions -- **Common Next Steps** - Advanced features to explore (commented until guides exist) -- **Related Resources** - Specific links to relevant documentation - -### Content Quality - -- **Copy-paste ready code examples** for all migration steps -- **Before/after comparisons** showing React Router v6 vs TanStack Router syntax -- **Real-world scenarios** covering nested routes, dynamic params, search params -- **TypeScript integration** with type safety guidance -- **Troubleshooting focus** addressing actual migration pain points - -## Next Priority Guidelines - -Based on the top-10 how-to guides priority list, the next highest priorities should be: - -1. **Guide #4: How to Fix Common Build and Bundler Issues** (if SSR guide still in progress) -2. **Guide #5: How to Integrate with Popular UI Libraries** -3. **Guide #6: How to Set Up Authentication and Protected Routes** - -### Implementation Notes - -- Each guide should follow the established pattern from deploy-to-production.md -- Cross-reference between guides as they become available -- Focus on practical, copy-paste ready solutions -- Address real GitHub issues and pain points mentioned in the priority analysis - -## Impact - -This migration guide addresses: -- **High priority user need** - Large React Router v6 user base requiring migration -- **Real developer pain points** - API differences, breaking changes, component refactoring -- **Productivity improvement** - Reduces migration friction from hours/days to 2-4 hours -- **Type safety benefits** - Guides users to TanStack Router's superior TypeScript experience - -The guide is positioned to significantly reduce migration support requests and improve developer adoption of TanStack Router. \ No newline at end of file From c669145541cde09aae75c46f56f053cbe8d7b9a5 Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Fri, 18 Jul 2025 22:26:57 +0000 Subject: [PATCH 3/3] ci: apply automated fixes --- .../react/how-to/migrate-from-react-router.md | 59 ++++++++++++++++--- 1 file changed, 50 insertions(+), 9 deletions(-) diff --git a/docs/router/framework/react/how-to/migrate-from-react-router.md b/docs/router/framework/react/how-to/migrate-from-react-router.md index ad3b5b2436..7a949de3a6 100644 --- a/docs/router/framework/react/how-to/migrate-from-react-router.md +++ b/docs/router/framework/react/how-to/migrate-from-react-router.md @@ -15,7 +15,7 @@ This guide provides a step-by-step process to migrate your application from Reac ### What You'll Accomplish - Remove React Router v6 dependencies and components -- Install and configure TanStack Router +- Install and configure TanStack Router - Convert route definitions to file-based routing - Update navigation components and hooks - Implement type-safe routing patterns @@ -30,12 +30,14 @@ This guide provides a step-by-step process to migrate your application from Reac Before making any changes, prepare your environment and codebase: **1.1 Create a backup branch** + ```bash git checkout -b migrate-to-tanstack-router git push -u origin migrate-to-tanstack-router ``` **1.2 Install TanStack Router (keep React Router temporarily)** + ```bash # Install TanStack Router npm install @tanstack/react-router @@ -47,6 +49,7 @@ npm install -D @tanstack/router-plugin @tanstack/react-router-devtools **1.3 Set up the router plugin for your bundler** For **Vite** users, update your `vite.config.ts`: + ```typescript import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' @@ -67,6 +70,7 @@ For **other bundlers**, see our [bundler configuration guides](../routing/). **2.1 Create router configuration file** Create `tsr.config.json` in your project root: + ```json { "routesDirectory": "./src/routes", @@ -76,6 +80,7 @@ Create `tsr.config.json` in your project root: ``` **2.2 Create routes directory** + ```bash mkdir src/routes ``` @@ -85,6 +90,7 @@ mkdir src/routes **3.1 Identify your current React Router structure** Examine your existing React Router setup. Look for: + - `createBrowserRouter` or `BrowserRouter` usage - `Routes` and `Route` components - Nested route patterns @@ -94,6 +100,7 @@ Examine your existing React Router setup. Look for: **3.2 Create root route** Create `src/routes/__root.tsx`: + ```typescript import { createRootRoute, Link, Outlet } from '@tanstack/react-router' import { TanStackRouterDevtools } from '@tanstack/react-router-devtools' @@ -121,6 +128,7 @@ export const Route = createRootRoute({ **3.3 Create index route** Create `src/routes/index.tsx` for your home page: + ```typescript import { createFileRoute } from '@tanstack/react-router' @@ -142,6 +150,7 @@ function Index() { For each static route in React Router like `/about`, create corresponding files: **React Router v6:** + ```typescript // In your router config { @@ -152,6 +161,7 @@ For each static route in React Router like `/about`, create corresponding files: **TanStack Router equivalent:** Create `src/routes/about.tsx`: + ```typescript import { createFileRoute } from '@tanstack/react-router' @@ -167,6 +177,7 @@ function About() { **3.5 Convert dynamic routes** **React Router v6:** + ```typescript // Route definition { @@ -185,6 +196,7 @@ function Post() { **TanStack Router equivalent:** Create `src/routes/posts/$postId.tsx`: + ```typescript import { createFileRoute } from '@tanstack/react-router' @@ -201,6 +213,7 @@ function Post() { **3.6 Convert nested routes** **React Router v6:** + ```typescript { path: "/posts", @@ -220,6 +233,7 @@ function Post() { **TanStack Router equivalent:** Create `src/routes/posts.tsx` (layout): + ```typescript import { createFileRoute, Link, Outlet } from '@tanstack/react-router' @@ -246,6 +260,7 @@ function PostsLayout() { ``` Create `src/routes/posts/index.tsx`: + ```typescript import { createFileRoute } from '@tanstack/react-router' @@ -263,6 +278,7 @@ function PostsIndex() { **4.1 Create router instance** Create `src/router.tsx`: + ```typescript import { createRouter } from '@tanstack/react-router' @@ -287,6 +303,7 @@ export { router } Replace your React Router setup in `src/main.tsx` or `src/App.tsx`: **Before (React Router v6):** + ```typescript import { RouterProvider, createBrowserRouter } from 'react-router-dom' @@ -302,6 +319,7 @@ ReactDOM.createRoot(document.getElementById('root')!).render( ``` **After (TanStack Router):** + ```typescript import { RouterProvider } from '@tanstack/react-router' import { router } from './router' @@ -318,6 +336,7 @@ ReactDOM.createRoot(document.getElementById('root')!).render( **5.1 Update Link components** **React Router v6:** + ```typescript import { Link } from 'react-router-dom' @@ -326,6 +345,7 @@ import { Link } from 'react-router-dom' ``` **TanStack Router:** + ```typescript import { Link } from '@tanstack/react-router' @@ -336,6 +356,7 @@ import { Link } from '@tanstack/react-router' **5.2 Update imperative navigation** **React Router v6:** + ```typescript import { useNavigate } from 'react-router-dom' @@ -351,6 +372,7 @@ function Component() { ``` **TanStack Router:** + ```typescript import { useNavigate } from '@tanstack/react-router' @@ -370,13 +392,14 @@ function Component() { **6.1 Basic search params migration** **React Router v6:** + ```typescript import { useSearchParams } from 'react-router-dom' function Component() { const [searchParams, setSearchParams] = useSearchParams() const page = searchParams.get('page') || '1' - + const updatePage = (newPage: string) => { setSearchParams({ page: newPage }) } @@ -385,6 +408,7 @@ function Component() { **TanStack Router:** First, define search params validation in your route: + ```typescript import { createFileRoute } from '@tanstack/react-router' import { z } from 'zod' @@ -414,6 +438,7 @@ function Posts() { Only after everything is working with TanStack Router: **7.1 Remove React Router** + ```bash npm uninstall react-router-dom @types/react-router-dom ``` @@ -421,6 +446,7 @@ npm uninstall react-router-dom @types/react-router-dom **7.2 Clean up unused imports** Search your codebase for any remaining React Router imports: + ```bash # Find remaining React Router imports grep -r "react-router" src/ @@ -434,6 +460,7 @@ Remove any remaining imports and replace with TanStack Router equivalents. **8.1 Enable strict TypeScript** Update your `tsconfig.json`: + ```json { "compilerOptions": { @@ -446,6 +473,7 @@ Update your `tsconfig.json`: **8.2 Add search parameter validation** For routes with search parameters, add validation schemas: + ```typescript import { createFileRoute } from '@tanstack/react-router' import { z } from 'zod' @@ -469,25 +497,29 @@ export const Route = createFileRoute('/posts')({ Before deploying your migrated application: ### Router Configuration + - [ ] Router instance created and properly exported -- [ ] Route tree generated successfully +- [ ] Route tree generated successfully - [ ] TypeScript declarations registered - [ ] All route files follow naming conventions ### Route Migration + - [ ] All static routes converted to file-based routing - [ ] Dynamic routes updated with proper parameter syntax -- [ ] Nested routes maintain hierarchy +- [ ] Nested routes maintain hierarchy - [ ] Index routes created where needed - [ ] Layout routes preserve component structure ### Navigation Updates + - [ ] All Link components updated to TanStack Router - [ ] useNavigate hooks replaced and tested - [ ] Navigation parameters properly typed - [ ] Search parameter validation implemented ### Code Cleanup + - [ ] React Router dependencies removed - [ ] Unused imports cleaned up - [ ] No React Router references remain @@ -495,6 +527,7 @@ Before deploying your migrated application: - [ ] All tests passing ### Testing + - [ ] All routes accessible and rendering correctly - [ ] Navigation between routes working - [ ] Back/forward browser buttons functional @@ -511,6 +544,7 @@ Before deploying your migrated application: **Problem:** You have remaining React Router imports that conflict with TanStack Router. **Solution:** + 1. Search for all React Router imports: ```bash grep -r "react-router" src/ @@ -523,6 +557,7 @@ Before deploying your migrated application: **Problem:** TypeScript showing errors about route parameters not being typed correctly. **Solution:** + 1. Ensure your router is registered in the TypeScript module declaration: ```typescript declare module '@tanstack/react-router' { @@ -539,6 +574,7 @@ Before deploying your migrated application: **Problem:** Routes not rendering or 404 errors for valid routes. **Solution:** + 1. Check file naming follows TanStack Router conventions: - Dynamic routes: `$paramName.tsx` - Index routes: `index.tsx` @@ -551,6 +587,7 @@ Before deploying your migrated application: **Problem:** Search parameters not being read or updated correctly. **Solution:** + 1. Add search parameter validation to your route: ```typescript export const Route = createFileRoute('/posts')({ @@ -569,6 +606,7 @@ Before deploying your migrated application: **Problem:** Application builds successfully but has runtime errors. **Solution:** + 1. Clear your build cache: ```bash rm -rf node_modules/.cache @@ -583,14 +621,17 @@ Before deploying your migrated application: **Problem:** Application feels slower after migration. **Solution:** + 1. Enable code splitting with lazy routes: + ```typescript import { createLazyFileRoute } from '@tanstack/react-router' - + export const Route = createLazyFileRoute('/posts/$postId')({ component: Post, }) ``` + 2. Configure route preloading: ```typescript const router = createRouter({ @@ -605,11 +646,11 @@ Before deploying your migrated application: After successfully migrating to TanStack Router, consider these enhancements: - @@ -617,7 +658,7 @@ Uncomment as guides become available: ### Advanced Features to Explore - **Route-based code splitting** - Improve performance with lazy loading -- **Search parameter validation** - Type-safe URL state management +- **Search parameter validation** - Type-safe URL state management - **Route preloading** - Enhance perceived performance - **Route masking** - Advanced URL management - **SSR setup** - Server-side rendering capabilities @@ -631,4 +672,4 @@ Uncomment as guides become available: - [Navigation Guide](../guide/navigation.md) - Complete navigation patterns - [Search Parameters Guide](../guide/search-params.md) - Advanced search param usage - [Type Safety Guide](../guide/type-safety.md) - TypeScript integration details -- [TanStack Router Comparison](../comparison.md) - Feature comparison with other routers \ No newline at end of file +- [TanStack Router Comparison](../comparison.md) - Feature comparison with other routers