--- id: migrate-from-next-js title: Migrate from Next.js --- This guide provides a step-by-step process to migrate a project from the Next.js App Router to **TanStack Start**. We respect the powerful features of Next.js and aim to make this transition as smooth as possible. ## Step-by-Step (Basics) This step-by-step guide provides an overview of how to migrate your Next.js App Router project to TanStack Start. The goal is to help you understand the basic steps involved in the migration process so you can adapt them to your specific project needs. ### Prerequisites Before we begin, this guide assumes your project structure looks like this: ```txt ├── next.config.ts ├── package.json ├── postcss.config.mjs ├── public │ ├── file.svg │ ├── globe.svg │ ├── next.svg │ ├── vercel.svg │ └── window.svg ├── README.md ├── src │ └── app │ ├── favicon.ico │ ├── globals.css │ ├── layout.tsx │ └── page.tsx └── tsconfig.json ``` Alternatively, you can follow along by cloning the following [starter template](https://github.com/nrjdalal/awesome-templates/tree/main/next.js-apps/next.js-start): ```sh npx gitpick nrjdalal/awesome-templates/tree/main/next.js-apps/next.js-start next.js-start-er ``` This structure is a basic Next.js application using the App Router, which we will migrate to TanStack Start. ### 1. Remove Next.js First, uninstall Next.js and remove related configuration files: ```sh npm uninstall @tailwindcss/postcss next rm postcss.config.* next.config.* ``` ### 2. Install Required Dependencies TanStack Start leverages [Vite](https://vite.dev) and TanStack Router: ```sh npm i @tanstack/react-router @tanstack/react-start ``` For Tailwind CSS and resolving imports using path aliases: ```sh npm i -D vite @vitejs/plugin-react @tailwindcss/vite tailwindcss vite-tsconfig-paths ``` ### 3. Update Project Configuration Now that you've installed the necessary dependencies, update your project configuration files to work with TanStack Start. - `package.json` ```json { "type": "module", "scripts": { "dev": "vite dev", "build": "vite build", "start": "node .output/server/index.mjs" } } ``` - `vite.config.ts` ```ts // vite.config.ts import { defineConfig } from 'vite' import { tanstackStart } from '@tanstack/react-start/plugin/vite' import viteReact from '@vitejs/plugin-react' import tsconfigPaths from 'vite-tsconfig-paths' import tailwindcss from '@tailwindcss/vite' export default defineConfig({ server: { port: 3000, }, plugins: [ tailwindcss(), // Enables Vite to resolve imports using path aliases. tsconfigPaths(), tanstackStart({ srcDirectory: 'src', // This is the default router: { // Specifies the directory TanStack Router uses for your routes. routesDirectory: 'app', // Defaults to "routes", relative to srcDirectory }, }), viteReact(), ], }) ``` By default, `routesDirectory` is set to `routes`. To maintain consistency with Next.js App Router conventions, you can set it to `app` instead. ### 4. Adapt the Root Layout > TanStack Start uses a routing approach similar to Remix, with some changes to support nested structures and special features using tokens. Learn more about it at [Routing Concepts](/router/latest/docs/framework/react/routing/routing-concepts) guide. Instead of `layout.tsx`, create a file named `__root.tsx` in the `src/app` directory. This file will serve as the root layout for your application. - `src/app/layout.tsx` to `src/app/__root.tsx` ```tsx - import type { Metadata } from "next" // [!code --] import { Outlet, createRootRoute, HeadContent, Scripts, } from "@tanstack/react-router" import appCss from "./globals.css?url" - export const metadata: Metadata = { // [!code --] - title: "Create Next App", // [!code --] - description: "Generated by create next app", // [!code --] - } // [!code --] export const Route = createRootRoute({ head: () => ({ meta: [ { charSet: "utf-8" }, { name: "viewport", content: "width=device-width, initial-scale=1", }, { title: "TanStack Start Starter" } ], links: [ { rel: 'stylesheet', href: appCss, }, ], }), component: RootLayout, }) - export default function RootLayout({ // [!code --] - children, // [!code --] - }: Readonly<{ // [!code --] - children: React.ReactNode // [!code --] - }>) { // [!code --] - return ( // [!code --] - // [!code --] -
{children} // [!code --] - // [!code --] - ) // [!code --] - } // [!code --] function RootLayout() { return (
Font Sans
// [!code --] - } // [!code --] ``` Instead of `next/font`, use Tailwind CSS’s CSS-first approach. Install fonts (for example, from [Fontsource](https://github.com/fontsource/fontsource)): ```sh npm i -D @fontsource-variable/dm-sans @fontsource-variable/jetbrains-mono ``` Add the following to `src/app/globals.css`: ```css @import 'tailwindcss' source('../'); @import '@fontsource-variable/dm-sans'; /* [!code ++] */ @import '@fontsource-variable/jetbrains-mono'; /* [!code ++] */ @theme inline { --font-sans: 'DM Sans Variable', sans-serif; /* [!code ++] */ --font-mono: 'JetBrains Mono Variable', monospace; /* [!code ++] */ /* ... */ } /* ... */ ``` ### Fetching Data ```tsx - export default async function Page() { // [!code --] + export const Route = createFileRoute('/')({ // [!code ++] + component: Page, // [!code ++] + loader: async () => { // [!code ++] + const res = await fetch('https://api.vercel.app/blog') // [!code ++] + return res.json() // [!code ++] + }, // [!code ++] + }) // [!code ++] + function Page() { // [!code ++] - const data = await fetch('https://api.vercel.app/blog') // [!code --] - const posts = await data.json() // [!code --] + const posts = Route.useLoaderData() // [!code ++] return (