Skip to content
Source
Sign inSign up
TanStack/router

chore: update migration docs for next/image #5326

MergedAlemTuzlakmerged 1 commit intomain fromrefs/pull/5326/headmerged by schiller-manuel(GitHub profile, opens in a new tab)

AlemTuzlakcommented

Summary by CodeRabbit

  • Documentation
    • Expanded Next.js → TanStack Start migration guide.
    • Updated routing examples to createFileRoute with Route hooks (useParams, useLoaderData).
    • Rewrote server examples using createServerFn and server.handlers.GET within route declarations.
    • Replaced Next.js Link with TanStack Router’s Link (href → to).
    • Added Images section showing Unpic as a drop-in replacement for next/image with width/height examples.
    • Revised Home page snippet to a Route-based declaration and colocated component.
    • Clarified dynamic and catch-all route patterns and data loading.
    1. Walkthrough

      Updates the React migration guide to replace Next.js patterns with TanStack Start equivalents, including routing, links, loaders, server handlers, dynamic routes, and image handling via Unpic. All changes are confined to a single documentation file’s code examples and text.

      Changes

      Cohort / File(s)Summary of Changes
      Docs — React migration guide
      docs/start/framework/react/migrate-from-next-js.md
      Replaces Next.js Link with TanStack Router Link (href→to). Migrates routing to createFileRoute with Route.useParams and Route.useLoaderData. Shifts server examples to createServerFn and server.handlers.GET. Adds Unpic Image usage replacing next/image examples. Updates root/dynamic/catch-all route samples and loader-based data access.

      Sequence Diagram(s)

      sequenceDiagram
        autonumber
        actor User
        participant Router as TanStack Router
        participant Route as Route (createFileRoute)
        participant Loader as loader()
        participant Component as Page Component
      
        User->>Router: Navigate to "/"
        Router->>Route: Match route
        alt Loader defined
          Router->>Loader: Invoke loader()
          Loader-->>Router: Data
          Router->>Component: Render with Route.useLoaderData()
        else No loader
          Router->>Component: Render component
        end
      sequenceDiagram
        autonumber
        actor Client
        participant Route as /api/hello Route
        participant Server as server.handlers.GET
        participant Response
      
        Client->>Route: HTTP GET /api/hello
        Route->>Server: server.handlers.GET()
        Server-->>Response: JSON/text payload
        Route-->>Client: 200 OK with body

      Estimated code review effort

      🎯 3 (Moderate) | ⏱️ ~20 minutes

      • TanStack/router#5211 — Applies the same migration guide updates: createFileRoute/Route.useParams, Link href→to, createServerFn, and server.handlers patterns.

      Suggested labels

      documentation

      Poem

      A hop, a skip, I tweak the route—hooray! Links say “to” and loaders lead the way. Unpic pixels nibble light and neat, Server handlers drum a steady beat. From Next to Start, I thump with cheer— Carrots compiled, the path is clear! 🥕🐇

      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 describes updating migration docs for next/image, which matches the changes to the Images section but does not reflect the broader migration of routing, server functions, and component conventions implemented in this PR.
      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

      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

      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between af388a89f783b158f5725056192a278dde3155f8 and 2ff3eab27782e2a68c32509934b4e8f4385b1241.

      📒 Files selected for processing (1)
      • docs/start/framework/react/migrate-from-next-js.md (1 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
      docs/start/framework/react/migrate-from-next-js.md lines 309 to 326
      @@ -306 +306,21 @@
      306306
      307+### Images
      308+
      309+Next.js uses the `next/image` component for optimized images. In TanStack Start, you can use the package called [Unpic](https://unpic.pics/) for similar functionality
      310+and almost a drop-in replacement.
      311+
      312+```tsx
      313+import Image from "next/image" // [!code --]
      314+import { Image } from "@unpic/react"; // [!code ++]
      315+function Component() {
      316+ return (
      317+ <Image
      318+ src="/path/to/image.jpg"
      319+ alt="Description"
      320+ width="600" // [!code --]
      321+ height="400" // [!code --]
      322+ width={600} // [!code ++]
      323+ height={400} // [!code ++]
      324+ />
      325+ )
      326+}

      ⚠️ Potential issue | 🟠 Major

      Add install step for Unpic before showing usage.

      The new snippet imports @unpic/react, but we never tell readers to install it. Following the guide as written will crash at build time with “Cannot resolve module '@unpic/react'.” Please insert an install command (e.g. npm install @unpic/react) in this section before the code sample so the migration instructions are complete.

       ### Images
      
       Next.js uses the `next/image` component for optimized images. In TanStack Start, you can use the package called [Unpic](https://unpic.pics/) for similar functionality
       and almost a drop-in replacement.
      
      +Install the React component:
      +
      +```sh
      +npm install @unpic/react
      +```
      +
       ```tsx
       import Image from "next/image" // [!code --]
       import { Image } from "@unpic/react"; // [!code ++]
      🤖 Prompt for AI Agents
      In docs/start/framework/react/migrate-from-next-js.md around lines 309 to 326,
      the example imports @unpic/react but never tells readers to install it; add an
      install step immediately before the code block (e.g., a short sentence and the
      npm install @unpic/react command, with equivalent yarn/pnpm examples if you
      prefer) so users can install the package before trying the snippet and avoid the
      “Cannot resolve module '@unpic/react'” build error.

Sign in to join this conversation.