docs(Start): Revise migration guide for TanStack Start

[chribjel]

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.

[coderabbitai]

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

Loading

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 name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The 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	✅ Passed	No 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 66980e1 and ec66fd3.

📒 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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

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 0683940 and 66980e1.

📒 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.