Migration guides available in Next.js documentation
Next.js provides guides for migrating from popular frameworks to Next.js.
Next.js · Guides · all subjects
migration
29 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Minimum Node.js version requirement
The minimum Node.js version required for Next.js 13 is v18.17.
Can I use the Pages Router alongside the App Router in the same project?
Yes, the App Router and Pages Router can coexist in the same Next.js project. The `app` directory is intentionally designed to work simultaneously with the `pages` directory to allow for incremental page-by-page migration. However, when navigating between routes served by different routers, there will be a hard navigation. Automatic link prefetching with `next/link` will not prefetch across routers. Instead, you can optimize navigations between App Router and Pages Router to retain prefetched and fast page transitions.
Root layout in app directory must include html and body tags
The `app` directory must include a root layout file at `app/layout.tsx`. The root layout must define `<html>` and `<body>` tags since Next.js does not automatically create them. The root layout replaces both `pages/_app.tsx` and `pages/_document.tsx` files. File extensions `.js`, `.jsx`, or `.tsx` can be used for layout files.
Root layout component signature
A root layout must accept a `children` prop of type `React.ReactNode`. This prop will be populated with nested layouts or pages.
Pages Router to App Router file structure mapping
File structure mapping from Pages Router to App Router: `pages/index.js` → `app/page.js` (route `/`); `pages/about.js` → `app/about/page.js` (route `/about`); `pages/blog/[slug].js` → `app/blog/[slug]/page.js` (route `/blog/post-1`).
Pages in app directory are Server Components by default
Pages in the `app` directory are Server Components by default. This is different from the `pages` directory where pages are Client Components. This means pages can directly fetch data and access server-only resources without needing additional API routes.
Use 'use client' directive to create Client Components
To create a Client Component in the `app` directory, add the `'use client'` directive to the top of the file before any imports. This is similar to components in the `pages` directory and allows components to have state, effects, and browser APIs.
Metadata replaces next/head in app directory
In the `app` directory, the `next/head` React component is replaced with built-in SEO support using the `Metadata` type. Export a `metadata` object from layout or page files instead of using the `Head` component. Example: `export const metadata = { title: 'My Page Title' }`.
Data fetching in app directory uses fetch with cache options
In the `app` directory, data fetching uses `fetch()` with cache options instead of `getServerSideProps` and `getStaticProps`. Use `{ cache: 'force-cache' }` for static caching (similar to `getStaticProps`), `{ cache: 'no-store' }` for dynamic rendering on every request (similar to `getServerSideProps`), or `{ next: { revalidate: 10 } }` for revalidation after 10 seconds (similar to `getStaticProps` with `revalidate`).
Router hooks moved to next/navigation in app directory
In the `app` directory, router hooks are imported from `next/navigation` instead of `next/router`. The three main hooks are `useRouter()`, `usePathname()`, and `useSearchParams()`. These hooks can only be used in Client Components.
useRouter hook differences between pages and app directories
The new `useRouter` hook from `next/navigation` (app directory) differs from the `useRouter` hook from `next/router` (pages directory): it does not return `pathname` (use `usePathname()` instead), does not return `query` object (use `useSearchParams()` and `useParams()` instead), has no `isFallback`, `locale`, `locales`, `defaultLocales`, `domainLocales`, `basePath`, `asPath`, `isReady`, or `route` properties.
Request data access in app directory
The `app` directory provides read-only functions to retrieve request data: `headers()` (based on Web Headers API, usable in Server Components to retrieve request headers) and `cookies()` (based on Web Cookies API, usable in Server Components to retrieve cookies). Both return Promises that must be awaited.
getStaticPaths replaced by generateStaticParams
In the `app` directory, `getStaticPaths` is replaced with `generateStaticParams()`. It behaves similarly but has a simplified API that returns an array of parameter objects instead of nested `param` objects. Example: `generateStaticParams()` returns `[{ id: '1' }, { id: '2' }]` instead of `{ paths: [{ params: { id: '1' } }] }`.
dynamicParams controls fallback behavior in app directory
The `dynamicParams` route segment configuration replaces the `fallback` option from `getStaticPaths`. When `dynamicParams` is `true` (default), dynamic segments not included in `generateStaticParams` are generated on demand and cached. When `false`, they return a 404. The `fallback: 'blocking'` option is not included because streaming makes the difference between 'blocking' and 'true' negligible.
API Routes replaced by Route Handlers
API Routes in `pages/api/*` are replaced by Route Handlers using the `route.js` special file in the `app` directory. Route Handlers use the Web Request and Response APIs and are exported as functions named after HTTP methods (e.g., `export async function GET(request: Request) {}`).
Global styles restriction lifted in app directory
In the `pages` directory, global stylesheets can only be imported in `pages/_app.js`. In the `app` directory, this restriction is lifted. Global styles can be added to any layout, page, or component.
Tailwind CSS configuration for app directory
When using Tailwind CSS with the `app` directory, add the app directory to the `content` array in `tailwind.config.js`: `'./app/**/*.{js,ts,jsx,tsx,mdx}'`. Also import global styles in `app/layout.js`.
Script component migration to app directory
When migrating `next/script` to the `app` directory: move `beforeInteractive` scripts from `_document.js` to the root layout file (`app/layout.tsx`); the experimental `worker` strategy does not yet work in `app` and should be removed or modified; `onLoad`, `onReady`, and `onError` handlers will not work in Server Components and must be moved to a Client Component or removed.
Image component migration from next/future/image
Next.js 12 introduced improvements to the Image component via `next/future/image`. In Next.js 13, this new behavior is now the default for `next/image`. Two codemods are available: `next-image-to-legacy-image` (renames `next/image` to `next/legacy/image` to maintain old behavior) and `next-image-experimental` (adds inline styles and removes unused props to match new defaults; requires running `next-image-to-legacy-image` first).
Link component no longer requires nested a tag
In Next.js 13, the `<Link>` component no longer requires manually adding an `<a>` tag as a child. The `<Link>` component always renders `<a>` under the hood and allows forwarding props to the underlying tag. Example: `<Link href="/about">About</Link>` instead of `<Link href="/about"><a>About</a></Link>`.
Font optimization migration to next/font
Next.js 13 introduces the `next/font` module for font optimization. While CSS inlining still works in `pages`, it does not work in `app`. Use `next/font` in the `app` directory for font loading customization while maintaining performance and privacy. `next/font` is supported in both `pages` and `app` directories.
getLayout pattern replaced by native layouts
In the `pages` directory, the `getLayout` pattern (adding a property to page components) was used for per-page layouts. In the `app` directory, this is replaced by native support for nested layouts using `layout.js` files. Remove `Page.getLayout` properties and create `layout.js` files in nested directories instead.
Styles in app layout do not apply to pages directory
Styles imported in `app/layout.tsx` will not apply to routes in the `pages/*` directory. Keep `_app`/`_document` while migrating to prevent breaking `pages/*` routes. Delete them only after fully migrating.
Context providers must be Client Components in app directory
React Context providers must be moved to Client Components when migrating to the `app` directory. Mark provider components with the `'use client'` directive to enable context functionality.
Migration strategy from pages to app
The recommended migration strategy is incremental: (1) Update Node.js to v18.17 or higher; (2) Update Next.js to version 13.4 or greater; (3) Create the `app` directory; (4) Create a root layout; (5) Migrate pages incrementally. For each page: create a new Client Component file, move the page component logic there, then create a `page.js` Server Component that imports and renders the Client Component, moving data fetching logic into the Server Component.
ESLint upgrade required for Next.js 13
When upgrading to Next.js 13, upgrade ESLint by running the command to install `eslint-config-next@latest`. You may need to restart the ESLint server in VS Code (Cmd+Shift+P on Mac, Ctrl+Shift+P on Windows, then search 'ESLint: Restart ESLint Server') for changes to take effect.
error.js replaces pages/_error.js
In the `pages` directory, `pages/_error.js` handles errors globally. In the `app` directory, this is replaced with more granular `error.js` special files that can be placed at different levels of the route hierarchy to handle errors in specific segments.
not-found.js replaces pages/404.js
In the `pages` directory, `pages/404.js` handles not found errors. In the `app` directory, this is replaced with the `not-found.js` special file.