Skip to content
Source
Sign inSign up
TanStack/router

docs(Start): Revise migration guide for TanStack Start #5211

Mergedchribjel(GitHub profile, opens in a new tab)merged 2 commits intomain fromrefs/pull/5211/headmerged by schiller-manuel(GitHub profile, opens in a new tab)

Update installation instructions and routing configurations for TanStack Start.

Summary by CodeRabbit

  • Documentation
    • Updated React migration guide from Next.js with current routing conventions and defaults.
    • Adjusted installation guidance to reflect updated tooling and plugin placement.
    • Clarified new project layout defaults (explicit src directory and routes location).
    • Renamed and simplified example entry file and setup steps.
    • Refreshed examples to use the new routing, link and server-function patterns for parity with Next.js App Router.
    1. Walkthrough

      Documentation for migrating from Next.js to React with TanStack Start was updated: install lines and tooling moved Vite-related packages into Tailwind/JS tooling, added tanstackStart srcDirectory and changed routesDirectory default to routes (examples use app), renamed src/start.tsx → src/router.tsx, and updated code examples to new public APIs (createFileRoute, Route.useParams(), Link to, createServerFn, server/handlers).

      Changes

      Cohort / File(s)Summary of Changes
      React migration docs update
      docs/start/framework/react/migrate-from-next-js.md
      Edited installation/tooling commands to move Vite packages into Tailwind/JS tooling; added srcDirectory option (default 'src') and changed routesDirectory default to 'routes' (examples recommend 'app' for Next parity). Updated examples: rename src/start.tsx → src/router.tsx; switch to createFileRoute for route definitions; replace params usage with Route.useParams(); change Link href → Link to; introduce createServerFn and updated server route/handler patterns and imports.

      Sequence Diagram(s)

      sequenceDiagram
        autonumber
        actor Client
        participant Router as Router (createFileRoute / Route)
        participant Server as Server (createServerFn)
      
        Client->>Router: navigate (Link to="/posts/1")
        Router->>Router: Route.useParams() -> { id: "1" }
        Router->>Router: Route.loader() / useLoaderData()
        Router->>Server: call server function (createServerFn.handler)
        Server-->>Router: response (data/json)
        Router-->>Client: render component with data
        Note right of Router #D6EAF8: New/public APIs used:\ncreateFileRoute, Route.useParams,\nuseLoaderData, createServerFn

      Estimated code review effort

      🎯 3 (Moderate) | ⏱️ ~20 minutes

      Poem

      I nibble docs with careful bite, Moved routes from src into the light. createFileRoute plants a tiny sign, Link to hops paths that now align. Server functions hum — a tidy line. 🐰

      Pre-merge checks and finishing touches

      ✅ Passed checks (3 passed)
      Check nameStatusExplanation
      Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
      Title Check✅ PassedThe title clearly states that the migration guide for TanStack Start has been revised, aligning with updates to installation instructions and routing configuration in the documentation. It is concise and specific to the primary change in the pull request.
      Docstring Coverage✅ PassedNo functions found in the changes. Docstring coverage check skipped.
      ✨ Finishing touches
      🧪 Generate unit tests
      • Create PR with unit tests
      • Post copyable unit tests in a comment

      📜 Recent review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 66980e145fdf86b8954982caa45fc889032be110 and ec66fd3e9cf3bc2a0386d7bec4710124ffb24cba.

      📒 Files selected for processing (1)
      • docs/start/framework/react/migrate-from-next-js.md (3 hunks)
      🧰 Additional context used
      📓 Path-based instructions (2)
      docs/**/*.{md,mdx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use internal docs links relative to the docs/ folder (e.g., ./guide/data-loading)

      Files:

      • docs/start/framework/react/migrate-from-next-js.md
      docs/{router,start}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Place router docs under docs/router/ and start framework docs under docs/start/

      Files:

      • docs/start/framework/react/migrate-from-next-js.md
      🔇 Additional comments (14)
      docs/start/framework/react/migrate-from-next-js.md (14)

      58-58: This change has been addressed based on previous review feedback.

      The installation command now correctly installs only the TanStack runtime dependencies, with build tooling moved to dev dependencies as recommended.


      64-64: Build tooling properly categorized as dev dependencies.

      Good improvement! The Vite ecosystem packages are now correctly installed as dev dependencies alongside Tailwind CSS tooling.


      103-106: Configuration values updated to reflect new TanStack Start defaults.

      The srcDirectory setting with explicit 'src' value and routesDirectory changed from 'src/app' to 'app' align with the createFileRoute function's requirements. The documentation correctly explains these are relative to the srcDirectory.


      114-114: Documentation correctly explains the routing directory defaults.

      The clarification about routesDirectory defaulting to 'routes' with the option to use 'app' for Next.js parity is helpful and accurate.


      186-188: Correct usage of createFileRoute API.

      The createFileRoute('/') usage follows the proper API pattern where the function accepts a route path string and returns a function that accepts RouteOptions. The route must be exported as Route for proper code generation.


      217-217: File renamed to align with new conventions.

      The change from src/start.tsx to src/router.tsx reflects updated naming conventions in the TanStack Start framework.


      276-277: Correct migration from Next.js dynamic routes.

      The createFileRoute('/app/posts/$slug') syntax properly defines a dynamic route segment, and the Route component provides the correct API surface.


      282-282: Correct usage of Route.useParams() API.

      The Route.useParams() method is the correct way to access parsed path parameters in TanStack Router file-based routes.


      289-289: Correct usage of Route.useSearch() API.

      The Route.useSearch() method correctly accesses search parameters in TanStack Router, providing proper type safety.


      301-301: Link component API updated correctly.

      The change from href to to prop aligns with TanStack Router's Link component API, which differs from Next.js.


      314-317: Server Functions API migration correctly demonstrated.

      The transition from Next.js server actions to TanStack Start's createServerFn().handler() pattern follows the proper Server Functions API.


      326-334: Server Routes API migration correctly demonstrated.

      The migration from Next.js API route handlers to TanStack Start's server routes using createFileRoute with server.handlers configuration follows the documented API pattern.


      381-387: Data loading pattern migration correctly demonstrated.

      The migration from Next.js async components to TanStack Router's loader function pattern correctly demonstrates how to move data fetching from component-level to route-level.


      392-392: Correct usage of Route.useLoaderData().

      The Route.useLoaderData() method is the correct way to access data loaded by the route's loader function.


      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    2. Actionable comments posted: 1

      Caution

      Some comments are outside the diff and can’t be posted inline due to platform limitations.

      ⚠️ Outside diff range comments (2)
      docs/start/framework/react/migrate-from-next-js.md (2)

      118-118: Use internal relative docs links per repo guidelines.

      Replace absolute site links with paths relative to docs/.

      -... [Routing Concepts](/router/latest/docs/framework/react/routing/routing-concepts) ...
      +... [Routing Concepts](../../../router/framework/react/routing/routing-concepts) ...
      -... [preloading functionality](/router/latest/docs/framework/react/guide/preloading) ...
      -... [caching staleness](/router/latest/docs/framework/react/guide/data-loading) ...
      +... [preloading functionality](../../../router/framework/react/guide/preloading) ...
      +... [caching staleness](../../../router/framework/react/guide/data-loading) ...
      -Learn more about the [Routing Concepts](/router/latest/docs/framework/react/routing/routing-concepts).
      +Learn more about the [Routing Concepts](../../../router/framework/react/routing/routing-concepts).
      -... [Dynamic and Catch-All Routes](/router/latest/docs/framework/react/routing/routing-concepts#dynamic-route-segments).
      +... [Dynamic and Catch-All Routes](../../../router/framework/react/routing/routing-concepts#dynamic-route-segments).
      -Learn more about the [Links](/router/latest/docs/framework/react/guide/navigation#link-component).
      +Learn more about the [Links](../../../router/framework/react/guide/navigation#link-component).

      Also applies to: 233-234, 264-264, 291-291, 305-305


      270-285: Fix incorrect route path in dynamic route example.

      The path passed to createFileRoute should not include the app folder prefix. It should be the actual URL path.

      -export const Route = createFileRoute('/app/posts/$slug')({
      +export const Route = createFileRoute('/posts/$slug')({
         component: Page,
       })
      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 06839407b9246f406615ba529c35b8fed8e753c1 and 66980e145fdf86b8954982caa45fc889032be110.

      📒 Files selected for processing (1)
      • docs/start/framework/react/migrate-from-next-js.md (3 hunks)
      🧰 Additional context used
      📓 Path-based instructions (2)
      docs/**/*.{md,mdx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use internal docs links relative to the docs/ folder (e.g., ./guide/data-loading)

      Files:

      • docs/start/framework/react/migrate-from-next-js.md
      docs/{router,start}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Place router docs under docs/router/ and start framework docs under docs/start/

      Files:

      • docs/start/framework/react/migrate-from-next-js.md
      🔇 Additional comments (3)
      docs/start/framework/react/migrate-from-next-js.md (3)

      114-114: LGTM: Clear note on routesDirectory default.

      Good clarification about the default and opting into app for Next.js parity.


      217-231: LGTM: Introducing src/router.tsx is consistent with Start’s router setup.


      103-111: Plugin order is correct — tanstackStart before @vitejs/plugin-react

      TanStack docs recommend placing tanstackStart(...) before viteReact(); the snippet already follows that. Optionally set tanstackStart({ customViteReactPlugin: true }) to let it manage the React plugin integration.

      OutdatedResolvedby coderabbitai[bot](GitHub profile, opens in a new tab)
    3. schiller-manuel(GitHub profile, opens in a new tab)replied on docs/start/framework/react/migrate-from-next-js.md lines 58 to 59

      yep thats better

    4. coderabbitai[bot](GitHub profile, opens in a new tab)replied on docs/start/framework/react/migrate-from-next-js.md lines 58 to 59

      Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

Sign in to join this conversation.