.
This commit is contained in:
Kismet Hasanaj
+970
@@ -0,0 +1,970 @@
|
||||
---
|
||||
title: How to migrate from Pages to the App Router
|
||||
nav_title: App Router
|
||||
description: Learn how to upgrade your existing Next.js application from the Pages Router to the App Router.
|
||||
---
|
||||
|
||||
This guide will help you:
|
||||
|
||||
- [Update your Next.js application from version 12 to version 13](#nextjs-version)
|
||||
- [Upgrade features that work in both the `pages` and the `app` directories](#upgrading-new-features)
|
||||
- [Incrementally migrate your existing application from `pages` to `app`](#migrating-from-pages-to-app)
|
||||
|
||||
## Upgrading
|
||||
|
||||
### Node.js Version
|
||||
|
||||
The minimum Node.js version is now **v18.17**. See the [Node.js documentation](https://nodejs.org/docs/latest-v18.x/api/) for more information.
|
||||
|
||||
### Next.js Version
|
||||
|
||||
To update to Next.js version 13, run the following command using your preferred package manager:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm add next@latest react@latest react-dom@latest
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm install next@latest react@latest react-dom@latest
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn add next@latest react@latest react-dom@latest
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun add next@latest react@latest react-dom@latest
|
||||
```
|
||||
|
||||
### ESLint Version
|
||||
|
||||
If you're using ESLint, you need to upgrade your ESLint version:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm add -D eslint-config-next@latest
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm install -D eslint-config-next@latest
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn add -D eslint-config-next@latest
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun add -D eslint-config-next@latest
|
||||
```
|
||||
|
||||
> **Good to know**: You may need to restart the ESLint server in VS Code for the ESLint changes to take effect. Open the Command Palette (`cmd+shift+p` on Mac; `ctrl+shift+p` on Windows) and search for `ESLint: Restart ESLint Server`.
|
||||
|
||||
## Next Steps
|
||||
|
||||
After you've updated, see the following sections for next steps:
|
||||
|
||||
- [Upgrade new features](#upgrading-new-features): A guide to help you upgrade to new features such as the improved Image and Link Components.
|
||||
- [Migrate from the `pages` to `app` directory](#migrating-from-pages-to-app): A step-by-step guide to help you incrementally migrate from the `pages` to the `app` directory.
|
||||
|
||||
## Upgrading New Features
|
||||
|
||||
Next.js 13 introduced the new [App Router](/docs/app) with new features and conventions. The new Router is available in the `app` directory and co-exists with the `pages` directory.
|
||||
|
||||
Upgrading to Next.js 13 does **not** require using the App Router. You can continue using `pages` with new features that work in both directories, such as the updated [Image component](#image-component), [Link component](#link-component), [Script component](#script-component), and [Font optimization](#font-optimization).
|
||||
|
||||
### `<Image/>` Component
|
||||
|
||||
Next.js 12 introduced new improvements to the Image Component with a temporary import: `next/future/image`. These improvements included less client-side JavaScript, easier ways to extend and style images, better accessibility, and native browser lazy loading.
|
||||
|
||||
In version 13, this new behavior is now the default for `next/image`.
|
||||
|
||||
There are two codemods to help you migrate to the new Image Component:
|
||||
|
||||
- [**`next-image-to-legacy-image` codemod**](/docs/app/guides/upgrading/codemods#next-image-to-legacy-image): Safely and automatically renames `next/image` imports to `next/legacy/image`. Existing components will maintain the same behavior.
|
||||
- [**`next-image-experimental` codemod**](/docs/app/guides/upgrading/codemods#next-image-experimental): Dangerously adds inline styles and removes unused props. This will change the behavior of existing components to match the new defaults. To use this codemod, you need to run the `next-image-to-legacy-image` codemod first.
|
||||
|
||||
### `<Link>` Component
|
||||
|
||||
The [`<Link>` Component](/docs/app/api-reference/components/link) no longer requires manually adding an `<a>` tag as a child. This behavior was added as an experimental option in [version 12.2](https://nextjs.org/blog/next-12-2) and is now the default. In Next.js 13, `<Link>` always renders `<a>` and allows you to forward props to the underlying tag.
|
||||
|
||||
For example:
|
||||
|
||||
```jsx
|
||||
import Link from 'next/link'
|
||||
|
||||
// Next.js 12: `<a>` has to be nested otherwise it's excluded
|
||||
<Link href="/about">
|
||||
<a>About</a>
|
||||
</Link>
|
||||
|
||||
// Next.js 13: `<Link>` always renders `<a>` under the hood
|
||||
<Link href="/about">
|
||||
About
|
||||
</Link>
|
||||
```
|
||||
|
||||
To upgrade your links to Next.js 13, you can use the [`new-link` codemod](/docs/app/guides/upgrading/codemods#new-link).
|
||||
|
||||
### `<Script>` Component
|
||||
|
||||
The behavior of [`next/script`](/docs/app/api-reference/components/script) has been updated to support both `pages` and `app`, but some changes need to be made to ensure a smooth migration:
|
||||
|
||||
- Move any `beforeInteractive` scripts you previously included in `_document.js` to the root layout file (`app/layout.tsx`).
|
||||
- The experimental `worker` strategy does not yet work in `app` and scripts denoted with this strategy will either have to be removed or modified to use a different strategy (e.g. `lazyOnload`).
|
||||
- `onLoad`, `onReady`, and `onError` handlers will not work in Server Components so make sure to move them to a [Client Component](/docs/app/getting-started/server-and-client-components) or remove them altogether.
|
||||
|
||||
### Font Optimization
|
||||
|
||||
Previously, Next.js helped you optimize fonts by [inlining font CSS](/docs/app/api-reference/components/font). Version 13 introduces the new [`next/font`](/docs/app/api-reference/components/font) module which gives you the ability to customize your font loading experience while still ensuring great performance and privacy. `next/font` is supported in both the `pages` and `app` directories.
|
||||
|
||||
While [inlining CSS](/docs/app/api-reference/components/font) still works in `pages`, it does not work in `app`. You should use [`next/font`](/docs/app/api-reference/components/font) instead.
|
||||
|
||||
See the [Font Optimization](/docs/app/api-reference/components/font) page to learn how to use `next/font`.
|
||||
|
||||
## Migrating from `pages` to `app`
|
||||
|
||||
> **🎥 Watch:** Learn how to incrementally adopt the App Router → [YouTube (16 minutes)](https://www.youtube.com/watch?v=YQMSietiFm0).
|
||||
|
||||
Moving to the App Router may be the first time using React features that Next.js builds on top of such as Server Components, Suspense, and more. When combined with new Next.js features such as [special files](/docs/app/api-reference/file-conventions) and [layouts](/docs/app/api-reference/file-conventions/layout), migration means new concepts, mental models, and behavioral changes to learn.
|
||||
|
||||
We recommend reducing the combined complexity of these updates by breaking down your migration into smaller steps. The `app` directory is intentionally designed to work simultaneously with the `pages` directory to allow for incremental page-by-page migration.
|
||||
|
||||
- The `app` directory supports nested routes _and_ layouts. [Learn more](/docs/app/getting-started/layouts-and-pages).
|
||||
- Use nested folders to define routes and a special `page.js` file to make a route segment publicly accessible. [Learn more](#step-4-migrating-pages).
|
||||
- [Special file conventions](/docs/app/api-reference/file-conventions) are used to create UI for each route segment. The most common special files are `page.js` and `layout.js`.
|
||||
- Use `page.js` to define UI unique to a route.
|
||||
- Use `layout.js` to define UI that is shared across multiple routes.
|
||||
- `.js`, `.jsx`, or `.tsx` file extensions can be used for special files.
|
||||
- You can colocate other files inside the `app` directory such as components, styles, tests, and more. [Learn more](/docs/app).
|
||||
- Data fetching functions like `getServerSideProps` and `getStaticProps` have been replaced with [a new API](/docs/app/getting-started/fetching-data) inside `app`. `getStaticPaths` has been replaced with [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params).
|
||||
- `pages/_app.js` and `pages/_document.js` have been replaced with a single `app/layout.js` root layout. [Learn more](/docs/app/api-reference/file-conventions/layout#root-layout).
|
||||
- `pages/_error.js` has been replaced with more granular `error.js` special files. [Learn more](/docs/app/getting-started/error-handling).
|
||||
- `pages/404.js` has been replaced with the [`not-found.js`](/docs/app/api-reference/file-conventions/not-found) file.
|
||||
- `pages/api/*` API Routes have been replaced with the [`route.js`](/docs/app/api-reference/file-conventions/route) (Route Handler) special file.
|
||||
|
||||
### Step 1: Creating the `app` directory
|
||||
|
||||
Update to the latest Next.js version (requires 13.4 or greater):
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm add next@latest
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm install next@latest
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn add next@latest
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun add next@latest
|
||||
```
|
||||
|
||||
Then, create a new `app` directory at the root of your project (or `src/` directory).
|
||||
|
||||
### Step 2: Creating a Root Layout
|
||||
|
||||
Create a new `app/layout.tsx` file inside the `app` directory. This is a [root layout](/docs/app/api-reference/file-conventions/layout#root-layout) that will apply to all routes inside `app`.
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
export default function RootLayout({
|
||||
// Layouts must accept a children prop.
|
||||
// This will be populated with nested layouts or pages
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export default function RootLayout({
|
||||
// Layouts must accept a children prop.
|
||||
// This will be populated with nested layouts or pages
|
||||
children,
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
- The `app` directory **must** include a root layout.
|
||||
- The root layout must define `<html>`, and `<body>` tags since Next.js does not automatically create them
|
||||
- The root layout replaces the `pages/_app.tsx` and `pages/_document.tsx` files.
|
||||
- `.js`, `.jsx`, or `.tsx` extensions can be used for layout files.
|
||||
|
||||
To manage `<head>` HTML elements, you can use the [built-in SEO support](/docs/app/getting-started/metadata-and-og-images):
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
import type { Metadata } from 'next'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'Home',
|
||||
description: 'Welcome to Next.js',
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export const metadata = {
|
||||
title: 'Home',
|
||||
description: 'Welcome to Next.js',
|
||||
}
|
||||
```
|
||||
|
||||
#### Migrating `_document.js` and `_app.js`
|
||||
|
||||
If you have an existing `_app` or `_document` file, you can copy the contents (e.g. global styles) to the root layout (`app/layout.tsx`). Styles in `app/layout.tsx` will _not_ apply to `pages/*`. You should keep `_app`/`_document` while migrating to prevent your `pages/*` routes from breaking. Once fully migrated, you can then safely delete them.
|
||||
|
||||
If you are using any React Context providers, they will need to be moved to a [Client Component](/docs/app/getting-started/server-and-client-components).
|
||||
|
||||
#### Migrating the `getLayout()` pattern to Layouts (Optional)
|
||||
|
||||
Next.js recommended adding a [property to Page components](/docs/pages/building-your-application/routing/pages-and-layouts#layout-pattern) to achieve per-page layouts in the `pages` directory. This pattern can be replaced with native support for [nested layouts](/docs/app/api-reference/file-conventions/layout) in the `app` directory.
|
||||
|
||||
<details>
|
||||
<summary>See before and after example</summary>
|
||||
|
||||
**Before**
|
||||
|
||||
```jsx filename="components/DashboardLayout.js"
|
||||
export default function DashboardLayout({ children }) {
|
||||
return (
|
||||
<div>
|
||||
<h2>My Dashboard</h2>
|
||||
{children}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/dashboard/index.js"
|
||||
import DashboardLayout from '../components/DashboardLayout'
|
||||
|
||||
export default function Page() {
|
||||
return <p>My Page</p>
|
||||
}
|
||||
|
||||
Page.getLayout = function getLayout(page) {
|
||||
return <DashboardLayout>{page}</DashboardLayout>
|
||||
}
|
||||
```
|
||||
|
||||
**After**
|
||||
|
||||
- Remove the `Page.getLayout` property from `pages/dashboard/index.js` and follow the [steps for migrating pages](#step-4-migrating-pages) to the `app` directory.
|
||||
|
||||
```jsx filename="app/dashboard/page.js"
|
||||
export default function Page() {
|
||||
return <p>My Page</p>
|
||||
}
|
||||
```
|
||||
|
||||
- Move the contents of `DashboardLayout` into a new [Client Component](/docs/app/getting-started/server-and-client-components) to retain `pages` directory behavior.
|
||||
|
||||
```jsx filename="app/dashboard/DashboardLayout.js"
|
||||
'use client' // this directive should be at top of the file, before any imports.
|
||||
|
||||
// This is a Client Component
|
||||
export default function DashboardLayout({ children }) {
|
||||
return (
|
||||
<div>
|
||||
<h2>My Dashboard</h2>
|
||||
{children}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
- Import the `DashboardLayout` into a new `layout.js` file inside the `app` directory.
|
||||
|
||||
```jsx filename="app/dashboard/layout.js"
|
||||
import DashboardLayout from './DashboardLayout'
|
||||
|
||||
// This is a Server Component
|
||||
export default function Layout({ children }) {
|
||||
return <DashboardLayout>{children}</DashboardLayout>
|
||||
}
|
||||
```
|
||||
|
||||
- You can incrementally move non-interactive parts of `DashboardLayout.js` (Client Component) into `layout.js` (Server Component) to reduce the amount of component JavaScript you send to the client.
|
||||
|
||||
</details>
|
||||
|
||||
### Step 3: Migrating `next/head`
|
||||
|
||||
In the `pages` directory, the `next/head` React component is used to manage `<head>` HTML elements such as `title` and `meta` . In the `app` directory, `next/head` is replaced with the new [built-in SEO support](/docs/app/getting-started/metadata-and-og-images).
|
||||
|
||||
**Before:**
|
||||
|
||||
```tsx filename="pages/index.tsx" switcher
|
||||
import Head from 'next/head'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<>
|
||||
<Head>
|
||||
<title>My page title</title>
|
||||
</Head>
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="pages/index.js" switcher
|
||||
import Head from 'next/head'
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<>
|
||||
<Head>
|
||||
<title>My page title</title>
|
||||
</Head>
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**After:**
|
||||
|
||||
```tsx filename="app/page.tsx" switcher
|
||||
import type { Metadata } from 'next'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'My Page Title',
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return '...'
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/page.js" switcher
|
||||
export const metadata = {
|
||||
title: 'My Page Title',
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return '...'
|
||||
}
|
||||
```
|
||||
|
||||
[See all metadata options](/docs/app/api-reference/functions/generate-metadata).
|
||||
|
||||
### Step 4: Migrating Pages
|
||||
|
||||
- Pages in the [`app` directory](/docs/app) are [Server Components](/docs/app/getting-started/server-and-client-components) by default. This is different from the `pages` directory where pages are [Client Components](/docs/app/getting-started/server-and-client-components).
|
||||
- [Data fetching](/docs/app/getting-started/fetching-data) has changed in `app`. `getServerSideProps`, `getStaticProps` and `getInitialProps` have been replaced with a simpler API.
|
||||
- The `app` directory uses nested folders to define routes and a special `page.js` file to make a route segment publicly accessible.
|
||||
- | `pages` Directory | `app` Directory | Route |
|
||||
| ----------------- | --------------------- | -------------- |
|
||||
| `index.js` | `page.js` | `/` |
|
||||
| `about.js` | `about/page.js` | `/about` |
|
||||
| `blog/[slug].js` | `blog/[slug]/page.js` | `/blog/post-1` |
|
||||
|
||||
We recommend breaking down the migration of a page into two main steps:
|
||||
|
||||
- Step 1: Move the default exported Page Component into a new Client Component.
|
||||
- Step 2: Import the new Client Component into a new `page.js` file inside the `app` directory.
|
||||
|
||||
> **Good to know**: This is the easiest migration path because it has the most comparable behavior to the `pages` directory.
|
||||
|
||||
**Step 1: Create a new Client Component**
|
||||
|
||||
- Create a new separate file inside the `app` directory (i.e. `app/home-page.tsx` or similar) that exports a Client Component. To define Client Components, add the `'use client'` directive to the top of the file (before any imports).
|
||||
- Similar to the Pages Router, there is an [optimization step](/docs/app/getting-started/server-and-client-components#on-the-client-first-load) to prerender Client Components to static HTML on the initial page load.
|
||||
- Move the default exported page component from `pages/index.js` to `app/home-page.tsx`.
|
||||
|
||||
```tsx filename="app/home-page.tsx" switcher
|
||||
'use client'
|
||||
|
||||
// This is a Client Component (same as components in the `pages` directory)
|
||||
// It receives data as props, has access to state and effects, and is
|
||||
// prerendered on the server during the initial page load.
|
||||
export default function HomePage({ recentPosts }) {
|
||||
return (
|
||||
<div>
|
||||
{recentPosts.map((post) => (
|
||||
<div key={post.id}>{post.title}</div>
|
||||
))}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/home-page.js" switcher
|
||||
'use client'
|
||||
|
||||
// This is a Client Component. It receives data as props and
|
||||
// has access to state and effects just like Page components
|
||||
// in the `pages` directory.
|
||||
export default function HomePage({ recentPosts }) {
|
||||
return (
|
||||
<div>
|
||||
{recentPosts.map((post) => (
|
||||
<div key={post.id}>{post.title}</div>
|
||||
))}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2: Create a new page**
|
||||
|
||||
- Create a new `app/page.tsx` file inside the `app` directory. This is a Server Component by default.
|
||||
- Import the `home-page.tsx` Client Component into the page.
|
||||
- If you were fetching data in `pages/index.js`, move the data fetching logic directly into the Server Component using the new [data fetching APIs](/docs/app/getting-started/fetching-data). See the [data fetching upgrade guide](#step-6-migrating-data-fetching-methods) for more details.
|
||||
|
||||
```tsx filename="app/page.tsx" switcher
|
||||
// Import your Client Component
|
||||
import HomePage from './home-page'
|
||||
|
||||
async function getPosts() {
|
||||
const res = await fetch('https://...')
|
||||
const posts = await res.json()
|
||||
return posts
|
||||
}
|
||||
|
||||
export default async function Page() {
|
||||
// Fetch data directly in a Server Component
|
||||
const recentPosts = await getPosts()
|
||||
// Forward fetched data to your Client Component
|
||||
return <HomePage recentPosts={recentPosts} />
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/page.js" switcher
|
||||
// Import your Client Component
|
||||
import HomePage from './home-page'
|
||||
|
||||
async function getPosts() {
|
||||
const res = await fetch('https://...')
|
||||
const posts = await res.json()
|
||||
return posts
|
||||
}
|
||||
|
||||
export default async function Page() {
|
||||
// Fetch data directly in a Server Component
|
||||
const recentPosts = await getPosts()
|
||||
// Forward fetched data to your Client Component
|
||||
return <HomePage recentPosts={recentPosts} />
|
||||
}
|
||||
```
|
||||
|
||||
- If your previous page used `useRouter`, you'll need to update to the new routing hooks. [Learn more](/docs/app/api-reference/functions/use-router).
|
||||
- Start your development server and visit [`http://localhost:3000`](http://localhost:3000). You should see your existing index route, now served through the app directory.
|
||||
|
||||
### Step 5: Migrating Routing Hooks
|
||||
|
||||
A new router has been added to support the new behavior in the `app` directory.
|
||||
|
||||
In `app`, you should use the three new hooks imported from `next/navigation`: [`useRouter()`](/docs/app/api-reference/functions/use-router), [`usePathname()`](/docs/app/api-reference/functions/use-pathname), and [`useSearchParams()`](/docs/app/api-reference/functions/use-search-params).
|
||||
|
||||
- The new `useRouter` hook is imported from `next/navigation` and has different behavior to the `useRouter` hook in `pages` which is imported from `next/router`.
|
||||
- The [`useRouter` hook imported from `next/router`](/docs/pages/api-reference/functions/use-router) is not supported in the `app` directory but can continue to be used in the `pages` directory.
|
||||
- The new `useRouter` does not return the `pathname` string. Use the separate `usePathname` hook instead.
|
||||
- The new `useRouter` does not return the `query` object. Search parameters and dynamic route parameters are now separate. Use the `useSearchParams` and `useParams` hooks instead.
|
||||
- You can use `useSearchParams` and `usePathname` together to listen to page changes. See the [Router Events](/docs/app/api-reference/functions/use-router#router-events) section for more details.
|
||||
- These new hooks are only supported in Client Components. They cannot be used in Server Components.
|
||||
|
||||
```tsx filename="app/example-client-component.tsx" switcher
|
||||
'use client'
|
||||
|
||||
import { useRouter, usePathname, useSearchParams } from 'next/navigation'
|
||||
|
||||
export default function ExampleClientComponent() {
|
||||
const router = useRouter()
|
||||
const pathname = usePathname()
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/example-client-component.js" switcher
|
||||
'use client'
|
||||
|
||||
import { useRouter, usePathname, useSearchParams } from 'next/navigation'
|
||||
|
||||
export default function ExampleClientComponent() {
|
||||
const router = useRouter()
|
||||
const pathname = usePathname()
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
In addition, the new `useRouter` hook has the following changes:
|
||||
|
||||
- `isFallback` has been removed because `fallback` has [been replaced](#replacing-fallback).
|
||||
- The `locale`, `locales`, `defaultLocales`, `domainLocales` values have been removed because built-in i18n Next.js features are no longer necessary in the `app` directory. [Learn more about i18n](/docs/app/guides/internationalization).
|
||||
- `basePath` has been removed. The alternative will not be part of `useRouter`. It has not yet been implemented.
|
||||
- `asPath` has been removed because the concept of `as` has been removed from the new router.
|
||||
- `isReady` has been removed because it is no longer necessary. During [prerendering](/docs/app/glossary#prerendering), any component that uses the [`useSearchParams()`](/docs/app/api-reference/functions/use-search-params) hook will skip the prerendering step and instead be rendered on the client at runtime.
|
||||
- `route` has been removed. `usePathname` or `useSelectedLayoutSegments()` provide an alternative.
|
||||
|
||||
[View the `useRouter()` API reference](/docs/app/api-reference/functions/use-router).
|
||||
|
||||
#### Sharing components between `pages` and `app`
|
||||
|
||||
To keep components compatible between the `pages` and `app` routers, refer to the [`useRouter` hook from `next/compat/router`](/docs/pages/api-reference/functions/use-router#the-nextcompatrouter-export).
|
||||
This is the `useRouter` hook from the `pages` directory, but intended to be used while sharing components between routers. Once you are ready to use it only on the `app` router, update to the new [`useRouter` from `next/navigation`](/docs/app/api-reference/functions/use-router).
|
||||
|
||||
### Step 6: Migrating Data Fetching Methods
|
||||
|
||||
The `pages` directory uses `getServerSideProps` and `getStaticProps` to fetch data for pages. Inside the `app` directory, these previous data fetching functions are replaced with a [simpler API](/docs/app/getting-started/fetching-data) built on top of `fetch()` and `async` React Server Components.
|
||||
|
||||
```tsx filename="app/page.tsx" switcher
|
||||
export default async function Page() {
|
||||
// This request should be cached until manually invalidated.
|
||||
// Similar to `getStaticProps`.
|
||||
// `force-cache` is the default and can be omitted.
|
||||
const staticData = await fetch(`https://...`, { cache: 'force-cache' })
|
||||
|
||||
// This request should be refetched on every request.
|
||||
// Similar to `getServerSideProps`.
|
||||
const dynamicData = await fetch(`https://...`, { cache: 'no-store' })
|
||||
|
||||
// This request should be cached with a lifetime of 10 seconds.
|
||||
// Similar to `getStaticProps` with the `revalidate` option.
|
||||
const revalidatedData = await fetch(`https://...`, {
|
||||
next: { revalidate: 10 },
|
||||
})
|
||||
|
||||
return <div>...</div>
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/page.js" switcher
|
||||
export default async function Page() {
|
||||
// This request should be cached until manually invalidated.
|
||||
// Similar to `getStaticProps`.
|
||||
// `force-cache` is the default and can be omitted.
|
||||
const staticData = await fetch(`https://...`, { cache: 'force-cache' })
|
||||
|
||||
// This request should be refetched on every request.
|
||||
// Similar to `getServerSideProps`.
|
||||
const dynamicData = await fetch(`https://...`, { cache: 'no-store' })
|
||||
|
||||
// This request should be cached with a lifetime of 10 seconds.
|
||||
// Similar to `getStaticProps` with the `revalidate` option.
|
||||
const revalidatedData = await fetch(`https://...`, {
|
||||
next: { revalidate: 10 },
|
||||
})
|
||||
|
||||
return <div>...</div>
|
||||
}
|
||||
```
|
||||
|
||||
#### Server-side Rendering (`getServerSideProps`)
|
||||
|
||||
In the `pages` directory, `getServerSideProps` is used to fetch data on the server and forward props to the default exported React component in the file. The initial HTML for the page is prerendered from the server, followed by "hydrating" the page in the browser (making it interactive).
|
||||
|
||||
```jsx filename="pages/dashboard.js"
|
||||
// `pages` directory
|
||||
|
||||
export async function getServerSideProps() {
|
||||
const res = await fetch(`https://...`)
|
||||
const projects = await res.json()
|
||||
|
||||
return { props: { projects } }
|
||||
}
|
||||
|
||||
export default function Dashboard({ projects }) {
|
||||
return (
|
||||
<ul>
|
||||
{projects.map((project) => (
|
||||
<li key={project.id}>{project.name}</li>
|
||||
))}
|
||||
</ul>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
In the App Router, we can colocate our data fetching inside our React components using [Server Components](/docs/app/getting-started/server-and-client-components). This allows us to send less JavaScript to the client, while maintaining the rendered HTML from the server.
|
||||
|
||||
By setting the `cache` option to `no-store`, we can indicate that the fetched data should [never be cached](/docs/app/getting-started/fetching-data). This is similar to `getServerSideProps` in the `pages` directory.
|
||||
|
||||
```tsx filename="app/dashboard/page.tsx" switcher
|
||||
// `app` directory
|
||||
|
||||
// This function can be named anything
|
||||
async function getProjects() {
|
||||
const res = await fetch(`https://...`, { cache: 'no-store' })
|
||||
const projects = await res.json()
|
||||
|
||||
return projects
|
||||
}
|
||||
|
||||
export default async function Dashboard() {
|
||||
const projects = await getProjects()
|
||||
|
||||
return (
|
||||
<ul>
|
||||
{projects.map((project) => (
|
||||
<li key={project.id}>{project.name}</li>
|
||||
))}
|
||||
</ul>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/dashboard/page.js" switcher
|
||||
// `app` directory
|
||||
|
||||
// This function can be named anything
|
||||
async function getProjects() {
|
||||
const res = await fetch(`https://...`, { cache: 'no-store' })
|
||||
const projects = await res.json()
|
||||
|
||||
return projects
|
||||
}
|
||||
|
||||
export default async function Dashboard() {
|
||||
const projects = await getProjects()
|
||||
|
||||
return (
|
||||
<ul>
|
||||
{projects.map((project) => (
|
||||
<li key={project.id}>{project.name}</li>
|
||||
))}
|
||||
</ul>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### Accessing Request Object
|
||||
|
||||
In the `pages` directory, you can retrieve request-based data based on the Node.js HTTP API.
|
||||
|
||||
For example, you can retrieve the `req` object from `getServerSideProps` and use it to retrieve the request's cookies and headers.
|
||||
|
||||
```jsx filename="pages/index.js"
|
||||
// `pages` directory
|
||||
|
||||
export async function getServerSideProps({ req, query }) {
|
||||
const authHeader = req.getHeaders()['authorization'];
|
||||
const theme = req.cookies['theme'];
|
||||
|
||||
return { props: { ... }}
|
||||
}
|
||||
|
||||
export default function Page(props) {
|
||||
return ...
|
||||
}
|
||||
```
|
||||
|
||||
The `app` directory exposes new read-only functions to retrieve request data:
|
||||
|
||||
- [`headers`](/docs/app/api-reference/functions/headers): Based on the Web Headers API, and can be used inside [Server Components](/docs/app/getting-started/server-and-client-components) to retrieve request headers.
|
||||
- [`cookies`](/docs/app/api-reference/functions/cookies): Based on the Web Cookies API, and can be used inside [Server Components](/docs/app/getting-started/server-and-client-components) to retrieve cookies.
|
||||
|
||||
```tsx filename="app/page.tsx" switcher
|
||||
// `app` directory
|
||||
import { cookies, headers } from 'next/headers'
|
||||
|
||||
async function getData() {
|
||||
const authHeader = (await headers()).get('authorization')
|
||||
|
||||
return '...'
|
||||
}
|
||||
|
||||
export default async function Page() {
|
||||
// You can use `cookies` or `headers` inside Server Components
|
||||
// directly or in your data fetching function
|
||||
const theme = (await cookies()).get('theme')
|
||||
const data = await getData()
|
||||
return '...'
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/page.js" switcher
|
||||
// `app` directory
|
||||
import { cookies, headers } from 'next/headers'
|
||||
|
||||
async function getData() {
|
||||
const authHeader = (await headers()).get('authorization')
|
||||
|
||||
return '...'
|
||||
}
|
||||
|
||||
export default async function Page() {
|
||||
// You can use `cookies` or `headers` inside Server Components
|
||||
// directly or in your data fetching function
|
||||
const theme = (await cookies()).get('theme')
|
||||
const data = await getData()
|
||||
return '...'
|
||||
}
|
||||
```
|
||||
|
||||
#### Static Site Generation (`getStaticProps`)
|
||||
|
||||
In the `pages` directory, the `getStaticProps` function is used to prerender a page at build time. This function can be used to fetch data from an external API or directly from a database, and pass this data down to the entire page as it's being generated during the build.
|
||||
|
||||
```jsx filename="pages/index.js"
|
||||
// `pages` directory
|
||||
|
||||
export async function getStaticProps() {
|
||||
const res = await fetch(`https://...`)
|
||||
const projects = await res.json()
|
||||
|
||||
return { props: { projects } }
|
||||
}
|
||||
|
||||
export default function Index({ projects }) {
|
||||
return projects.map((project) => <div>{project.name}</div>)
|
||||
}
|
||||
```
|
||||
|
||||
In the `app` directory, data fetching with [`fetch()`](/docs/app/api-reference/functions/fetch) will default to `cache: 'force-cache'`, which will cache the request data until manually invalidated. This is similar to `getStaticProps` in the `pages` directory.
|
||||
|
||||
```jsx filename="app/page.js"
|
||||
// `app` directory
|
||||
|
||||
// This function can be named anything
|
||||
async function getProjects() {
|
||||
const res = await fetch(`https://...`)
|
||||
const projects = await res.json()
|
||||
|
||||
return projects
|
||||
}
|
||||
|
||||
export default async function Index() {
|
||||
const projects = await getProjects()
|
||||
|
||||
return projects.map((project) => <div>{project.name}</div>)
|
||||
}
|
||||
```
|
||||
|
||||
#### Dynamic paths (`getStaticPaths`)
|
||||
|
||||
In the `pages` directory, the `getStaticPaths` function is used to define the dynamic paths that should be prerendered at build time.
|
||||
|
||||
```jsx filename="pages/posts/[id].js"
|
||||
// `pages` directory
|
||||
import PostLayout from '@/components/post-layout'
|
||||
|
||||
export async function getStaticPaths() {
|
||||
return {
|
||||
paths: [{ params: { id: '1' } }, { params: { id: '2' } }],
|
||||
}
|
||||
}
|
||||
|
||||
export async function getStaticProps({ params }) {
|
||||
const res = await fetch(`https://.../posts/${params.id}`)
|
||||
const post = await res.json()
|
||||
|
||||
return { props: { post } }
|
||||
}
|
||||
|
||||
export default function Post({ post }) {
|
||||
return <PostLayout post={post} />
|
||||
}
|
||||
```
|
||||
|
||||
In the `app` directory, `getStaticPaths` is replaced with [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params).
|
||||
|
||||
[`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) behaves similarly to `getStaticPaths`, but has a simplified API for returning route parameters and can be used inside [layouts](/docs/app/api-reference/file-conventions/layout). The return shape of `generateStaticParams` is an array of segments instead of an array of nested `param` objects or a string of resolved paths.
|
||||
|
||||
```jsx filename="app/posts/[id]/page.js"
|
||||
// `app` directory
|
||||
import PostLayout from '@/components/post-layout'
|
||||
|
||||
export async function generateStaticParams() {
|
||||
return [{ id: '1' }, { id: '2' }]
|
||||
}
|
||||
|
||||
async function getPost(params) {
|
||||
const res = await fetch(`https://.../posts/${(await params).id}`)
|
||||
const post = await res.json()
|
||||
|
||||
return post
|
||||
}
|
||||
|
||||
export default async function Post({ params }) {
|
||||
const post = await getPost(params)
|
||||
|
||||
return <PostLayout post={post} />
|
||||
}
|
||||
```
|
||||
|
||||
Using the name `generateStaticParams` is more appropriate than `getStaticPaths` for the new model in the `app` directory. The `get` prefix is replaced with a more descriptive `generate`, which sits better alone now that `getStaticProps` and `getServerSideProps` are no longer necessary. The `Paths` suffix is replaced by `Params`, which is more appropriate for nested routing with multiple dynamic segments.
|
||||
|
||||
---
|
||||
|
||||
#### Replacing `fallback`
|
||||
|
||||
In the `pages` directory, the `fallback` property returned from `getStaticPaths` is used to define the behavior of a page that isn't prerendered at build time. This property can be set to `true` to show a fallback page while the page is being generated, `false` to show a 404 page, or `blocking` to generate the page at request time.
|
||||
|
||||
```jsx filename="pages/posts/[id].js"
|
||||
// `pages` directory
|
||||
|
||||
export async function getStaticPaths() {
|
||||
return {
|
||||
paths: [],
|
||||
fallback: 'blocking'
|
||||
};
|
||||
}
|
||||
|
||||
export async function getStaticProps({ params }) {
|
||||
...
|
||||
}
|
||||
|
||||
export default function Post({ post }) {
|
||||
return ...
|
||||
}
|
||||
```
|
||||
|
||||
In the `app` directory the [`config.dynamicParams` property](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) controls how params outside of [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) are handled:
|
||||
|
||||
- **`true`**: (default) Dynamic segments not included in `generateStaticParams` are generated on demand.
|
||||
- **`false`**: Dynamic segments not included in `generateStaticParams` will return a 404.
|
||||
|
||||
This replaces the `fallback: true | false | 'blocking'` option of `getStaticPaths` in the `pages` directory. The `fallback: 'blocking'` option is not included in `dynamicParams` because the difference between `'blocking'` and `true` is negligible with streaming.
|
||||
|
||||
```jsx filename="app/posts/[id]/page.js"
|
||||
// `app` directory
|
||||
|
||||
export const dynamicParams = true;
|
||||
|
||||
export async function generateStaticParams() {
|
||||
return [...]
|
||||
}
|
||||
|
||||
async function getPost(params) {
|
||||
...
|
||||
}
|
||||
|
||||
export default async function Post({ params }) {
|
||||
const post = await getPost(params);
|
||||
|
||||
return ...
|
||||
}
|
||||
```
|
||||
|
||||
With [`dynamicParams`](/docs/app/api-reference/file-conventions/route-segment-config/dynamicParams) set to `true` (the default), when a route segment is requested that hasn't been generated, it will be server-rendered and cached.
|
||||
|
||||
#### Incremental Static Regeneration (`getStaticProps` with `revalidate`)
|
||||
|
||||
In the `pages` directory, the `getStaticProps` function allows you to add a `revalidate` field to automatically regenerate a page after a certain amount of time.
|
||||
|
||||
```jsx filename="pages/index.js"
|
||||
// `pages` directory
|
||||
|
||||
export async function getStaticProps() {
|
||||
const res = await fetch(`https://.../posts`)
|
||||
const posts = await res.json()
|
||||
|
||||
return {
|
||||
props: { posts },
|
||||
revalidate: 60,
|
||||
}
|
||||
}
|
||||
|
||||
export default function Index({ posts }) {
|
||||
return (
|
||||
<Layout>
|
||||
<PostList posts={posts} />
|
||||
</Layout>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
In the `app` directory, data fetching with [`fetch()`](/docs/app/api-reference/functions/fetch) can use `revalidate`, which will cache the request for the specified amount of seconds.
|
||||
|
||||
```jsx filename="app/page.js"
|
||||
// `app` directory
|
||||
|
||||
async function getPosts() {
|
||||
const res = await fetch(`https://.../posts`, { next: { revalidate: 60 } })
|
||||
const data = await res.json()
|
||||
|
||||
return data.posts
|
||||
}
|
||||
|
||||
export default async function PostList() {
|
||||
const posts = await getPosts()
|
||||
|
||||
return posts.map((post) => <div>{post.name}</div>)
|
||||
}
|
||||
```
|
||||
|
||||
#### API Routes
|
||||
|
||||
API Routes continue to work in the `pages/api` directory without any changes. However, they have been replaced by [Route Handlers](/docs/app/api-reference/file-conventions/route) in the `app` directory.
|
||||
|
||||
Route Handlers allow you to create custom request handlers for a given route using the Web [Request](https://developer.mozilla.org/docs/Web/API/Request) and [Response](https://developer.mozilla.org/docs/Web/API/Response) APIs.
|
||||
|
||||
```ts filename="app/api/route.ts" switcher
|
||||
export async function GET(request: Request) {}
|
||||
```
|
||||
|
||||
```js filename="app/api/route.js" switcher
|
||||
export async function GET(request) {}
|
||||
```
|
||||
|
||||
> **Good to know**: If you previously used API routes to call an external API from the client, you can now use [Server Components](/docs/app/getting-started/server-and-client-components) instead to securely fetch data. Learn more about [data fetching](/docs/app/getting-started/fetching-data).
|
||||
|
||||
#### Single-Page Applications
|
||||
|
||||
If you are also migrating to Next.js from a Single-Page Application (SPA) at the same time, see our [documentation](/docs/app/guides/single-page-applications) to learn more.
|
||||
|
||||
### Step 7: Styling
|
||||
|
||||
In the `pages` directory, global stylesheets are restricted to only `pages/_app.js`. With the `app` directory, this restriction has been lifted. Global styles can be added to any layout, page, or component.
|
||||
|
||||
- [CSS Modules](/docs/app/getting-started/css#css-modules)
|
||||
- [Tailwind CSS](/docs/app/getting-started/css#tailwind-css)
|
||||
- [Global Styles](/docs/app/getting-started/css#global-css)
|
||||
- [CSS-in-JS](/docs/app/guides/css-in-js)
|
||||
- [External Stylesheets](/docs/app/getting-started/css#external-stylesheets)
|
||||
- [Sass](/docs/app/guides/sass)
|
||||
|
||||
#### Tailwind CSS
|
||||
|
||||
If you're using Tailwind CSS, you'll need to add the `app` directory to your `tailwind.config.js` file:
|
||||
|
||||
```js filename="tailwind.config.js"
|
||||
module.exports = {
|
||||
content: [
|
||||
'./app/**/*.{js,ts,jsx,tsx,mdx}', // <-- Add this line
|
||||
'./pages/**/*.{js,ts,jsx,tsx,mdx}',
|
||||
'./components/**/*.{js,ts,jsx,tsx,mdx}',
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
You'll also need to import your global styles in your `app/layout.js` file:
|
||||
|
||||
```jsx filename="app/layout.js"
|
||||
import '../styles/globals.css'
|
||||
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>{children}</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Learn more about [styling with Tailwind CSS](/docs/app/getting-started/css#tailwind-css)
|
||||
|
||||
## Using App Router together with Pages Router
|
||||
|
||||
When navigating between routes served by the different Next.js routers, there will be a hard navigation. Automatic link prefetching with `next/link` will not prefetch across routers.
|
||||
|
||||
Instead, you can [optimize navigations](https://vercel.com/guides/optimizing-hard-navigations) between App Router and Pages Router to retain the prefetched and fast page transitions. [Learn more](https://vercel.com/guides/optimizing-hard-navigations).
|
||||
|
||||
## Codemods
|
||||
|
||||
Next.js provides Codemod transformations to help upgrade your codebase when a feature is deprecated. See [Codemods](/docs/app/guides/upgrading/codemods) for more information.
|
||||
+611
@@ -0,0 +1,611 @@
|
||||
---
|
||||
title: How to migrate from Create React App to Next.js
|
||||
nav_title: Create React App
|
||||
description: Learn how to migrate your existing React application from Create React App to Next.js.
|
||||
---
|
||||
|
||||
This guide will help you migrate an existing Create React App (CRA) site to Next.js.
|
||||
|
||||
## Why Switch?
|
||||
|
||||
There are several reasons why you might want to switch from Create React App to Next.js:
|
||||
|
||||
### Slow initial page loading time
|
||||
|
||||
Create React App uses purely client-side rendering. Client-side only applications, also known as [single-page applications (SPAs)](/docs/app/guides/single-page-applications), often experience slow initial page loading time. This happens due to a couple of reasons:
|
||||
|
||||
1. The browser needs to wait for the React code and your entire application bundle to download and run before your code is able to send requests to load data.
|
||||
2. Your application code grows with every new feature and dependency you add.
|
||||
|
||||
### No automatic code splitting
|
||||
|
||||
The previous issue of slow loading times can be somewhat mitigated with code splitting. However, if you try to do code splitting manually, you can inadvertently introduce network waterfalls. Next.js provides automatic code splitting and tree-shaking built into its router and build pipeline.
|
||||
|
||||
### Network waterfalls
|
||||
|
||||
A common cause of poor performance occurs when applications make sequential client-server requests to fetch data. One pattern for data fetching in a [SPA](/docs/app/guides/single-page-applications) is to render a placeholder, and then fetch data after the component has mounted. Unfortunately, a child component can only begin fetching data after its parent has finished loading its own data, resulting in a “waterfall” of requests.
|
||||
|
||||
While client-side data fetching is supported in Next.js, Next.js also lets you move data fetching to the server. This often eliminates client-server waterfalls altogether.
|
||||
|
||||
### Fast and intentional loading states
|
||||
|
||||
With built-in support for [streaming through React Suspense](/docs/app/getting-started/linking-and-navigating#streaming), you can define which parts of your UI load first and in what order, without creating network waterfalls.
|
||||
|
||||
This enables you to build pages that are faster to load and eliminate [layout shifts](https://vercel.com/blog/how-core-web-vitals-affect-seo).
|
||||
|
||||
### Choose the data fetching strategy
|
||||
|
||||
Depending on your needs, Next.js allows you to choose your data fetching strategy on a page or component-level basis. For example, you could fetch data from your CMS and render blog posts at build time (SSG) for quick load speeds, or fetch data at request time (SSR) when necessary.
|
||||
|
||||
### Proxy
|
||||
|
||||
[Next.js Proxy](/docs/app/api-reference/file-conventions/proxy) allows you to run code on the server before a request is completed. For instance, you can avoid a flash of unauthenticated content by redirecting a user to a login page in the proxy for authenticated-only pages. You can also use it for features like A/B testing, experimentation, and [internationalization](/docs/app/guides/internationalization).
|
||||
|
||||
### Built-in Optimizations
|
||||
|
||||
[Images](/docs/app/api-reference/components/image), [fonts](/docs/app/api-reference/components/font), and [third-party scripts](/docs/app/guides/scripts) often have a large impact on an application’s performance. Next.js includes specialized components and APIs that automatically optimize them for you.
|
||||
|
||||
## Migration Steps
|
||||
|
||||
Our goal is to get a working Next.js application as quickly as possible so that you can then adopt Next.js features incrementally. To begin with, we’ll treat your application as a purely client-side application ([SPA](/docs/app/guides/single-page-applications)) without immediately replacing your existing router. This reduces complexity and merge conflicts.
|
||||
|
||||
> **Note**: If you are using advanced CRA configurations such as a custom `homepage` field in your `package.json`, a custom service worker, or specific Babel/webpack tweaks, please see the **Additional Considerations** section at the end of this guide for tips on replicating or adapting these features in Next.js.
|
||||
|
||||
### Step 1: Install the Next.js Dependency
|
||||
|
||||
Install Next.js in your existing project:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm add next@latest
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm install next@latest
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn add next@latest
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun add next@latest
|
||||
```
|
||||
|
||||
### Step 2: Create the Next.js Configuration File
|
||||
|
||||
Create a `next.config.ts` at the root of your project (same level as your `package.json`). This file holds your [Next.js configuration options](/docs/app/api-reference/config/next-config-js).
|
||||
|
||||
```js filename="next.config.ts"
|
||||
import type { NextConfig } from 'next'
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
output: 'export', // Outputs a Single-Page Application (SPA)
|
||||
distDir: 'build', // Changes the build output directory to `build`
|
||||
}
|
||||
|
||||
export default nextConfig
|
||||
```
|
||||
|
||||
> **Note**: Using `output: 'export'` means you’re doing a static export. You will **not** have access to server-side features like SSR or APIs. You can remove this line to leverage Next.js server features.
|
||||
|
||||
### Step 3: Create the Root Layout
|
||||
|
||||
A Next.js [App Router](/docs/app) application must include a [root layout](/docs/app/api-reference/file-conventions/layout#root-layout) file, which is a [React Server Component](/docs/app/getting-started/server-and-client-components) that will wrap all your pages.
|
||||
|
||||
The closest equivalent of the root layout file in a CRA application is `public/index.html`, which includes your `<html>`, `<head>`, and `<body>` tags.
|
||||
|
||||
1. Create a new `app` directory inside your `src` folder (or at your project root if you prefer `app` at the root).
|
||||
2. Inside the `app` directory, create a `layout.tsx` (or `layout.js`) file:
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return '...'
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export default function RootLayout({ children }) {
|
||||
return '...'
|
||||
}
|
||||
```
|
||||
|
||||
Now copy the content of your old `index.html` into this `<RootLayout>` component. Replace `body div#root` (and `body noscript`) with `<div id="root">{children}</div>`.
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charSet="UTF-8" />
|
||||
<link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>React App</title>
|
||||
<meta name="description" content="Web site created..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>React App</title>
|
||||
<meta name="description" content="Web site created..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**: Next.js ignores CRA’s `public/manifest.json`, additional iconography, and [testing configuration](/docs/app/guides/testing) by default. If you need these, Next.js has support with its [Metadata API](/docs/app/getting-started/metadata-and-og-images) and [Testing](/docs/app/guides/testing) setup.
|
||||
|
||||
### Step 4: Metadata
|
||||
|
||||
Next.js automatically includes the `<meta charset="UTF-8" />` and `<meta name="viewport" content="width=device-width, initial-scale=1" />` tags, so you can remove them from `<head>`:
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
|
||||
<title>React App</title>
|
||||
<meta name="description" content="Web site created..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
|
||||
<title>React App</title>
|
||||
<meta name="description" content="Web site created..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Any [metadata files](/docs/app/getting-started/metadata-and-og-images#file-based-metadata) such as `favicon.ico`, `icon.png`, `robots.txt` are automatically added to the application `<head>` tag as long as you have them placed into the top level of the `app` directory. After moving [all supported files](/docs/app/getting-started/metadata-and-og-images#file-based-metadata) into the `app` directory you can safely delete their `<link>` tags:
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<title>React App</title>
|
||||
<meta name="description" content="Web site created..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<title>React App</title>
|
||||
<meta name="description" content="Web site created..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Finally, Next.js can manage your last `<head>` tags with the [Metadata API](/docs/app/getting-started/metadata-and-og-images). Move your final metadata info into an exported [`metadata` object](/docs/app/api-reference/functions/generate-metadata#metadata-object):
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
import type { Metadata } from 'next'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'React App',
|
||||
description: 'Web site created with Next.js.',
|
||||
}
|
||||
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export const metadata = {
|
||||
title: 'React App',
|
||||
description: 'Web site created with Next.js.',
|
||||
}
|
||||
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
With the above changes, you shifted from declaring everything in your `index.html` to using Next.js' convention-based approach built into the framework ([Metadata API](/docs/app/getting-started/metadata-and-og-images)). This approach enables you to more easily improve your SEO and web shareability of your pages.
|
||||
|
||||
### Step 5: Styles
|
||||
|
||||
Like CRA, Next.js supports [CSS Modules](/docs/app/getting-started/css#css-modules) out of the box. It also supports [global CSS imports](/docs/app/getting-started/css#global-css).
|
||||
|
||||
If you have a global CSS file, import it into your `app/layout.tsx`:
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
import '../index.css'
|
||||
|
||||
export const metadata = {
|
||||
title: 'React App',
|
||||
description: 'Web site created with Next.js.',
|
||||
}
|
||||
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
If you're using Tailwind CSS, see our [installation docs](/docs/app/getting-started/css#tailwind-css).
|
||||
|
||||
### Step 6: Create the Entrypoint Page
|
||||
|
||||
Create React App uses `src/index.tsx` (or `index.js`) as the entry point. In Next.js (App Router), each folder inside the `app` directory corresponds to a route, and each folder should have a `page.tsx`.
|
||||
|
||||
Since we want to keep the app as an SPA for now and intercept **all** routes, we’ll use an [optional catch-all route](/docs/app/api-reference/file-conventions/dynamic-routes#optional-catch-all-segments).
|
||||
|
||||
1. **Create a `[[...slug]]` directory inside `app`.**
|
||||
|
||||
```bash
|
||||
app
|
||||
┣ [[...slug]]
|
||||
┃ ┗ page.tsx
|
||||
┣ layout.tsx
|
||||
```
|
||||
|
||||
2. **Add the following to `page.tsx`**:
|
||||
|
||||
```tsx filename="app/[[...slug]]/page.tsx" switcher
|
||||
export function generateStaticParams() {
|
||||
return [{ slug: [''] }]
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return '...' // We'll update this
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/[[...slug]]/page.js" switcher
|
||||
export function generateStaticParams() {
|
||||
return [{ slug: [''] }]
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return '...' // We'll update this
|
||||
}
|
||||
```
|
||||
|
||||
This tells Next.js to generate a single route for the empty slug (`/`), effectively mapping **all** routes to the same page. This page is a [Server Component](/docs/app/getting-started/server-and-client-components), prerendered into static HTML.
|
||||
|
||||
### Step 7: Add a Client-Only Entrypoint
|
||||
|
||||
Next, we’ll embed your CRA’s root App component inside a [Client Component](/docs/app/getting-started/server-and-client-components) so that all logic remains client-side. If this is your first time using Next.js, it's worth knowing that clients components (by default) are still prerendered on the server. You can think about them as having the additional capability of running client-side JavaScript.
|
||||
|
||||
Create a `client.tsx` (or `client.js`) in `app/[[...slug]]/`:
|
||||
|
||||
```tsx filename="app/[[...slug]]/client.tsx" switcher
|
||||
'use client'
|
||||
|
||||
import dynamic from 'next/dynamic'
|
||||
|
||||
const App = dynamic(() => import('../../App'), { ssr: false })
|
||||
|
||||
export function ClientOnly() {
|
||||
return <App />
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/[[...slug]]/client.js" switcher
|
||||
'use client'
|
||||
|
||||
import dynamic from 'next/dynamic'
|
||||
|
||||
const App = dynamic(() => import('../../App'), { ssr: false })
|
||||
|
||||
export function ClientOnly() {
|
||||
return <App />
|
||||
}
|
||||
```
|
||||
|
||||
- The `'use client'` directive makes this file a **Client Component**.
|
||||
- The `dynamic` import with `ssr: false` disables server-side rendering for the `<App />` component, making it truly client-only (SPA).
|
||||
|
||||
Now update your `page.tsx` (or `page.js`) to use your new component:
|
||||
|
||||
```tsx filename="app/[[...slug]]/page.tsx" switcher
|
||||
import { ClientOnly } from './client'
|
||||
|
||||
export function generateStaticParams() {
|
||||
return [{ slug: [''] }]
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return <ClientOnly />
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/[[...slug]]/page.js" switcher
|
||||
import { ClientOnly } from './client'
|
||||
|
||||
export function generateStaticParams() {
|
||||
return [{ slug: [''] }]
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return <ClientOnly />
|
||||
}
|
||||
```
|
||||
|
||||
### Step 8: Update Static Image Imports
|
||||
|
||||
In CRA, importing an image file returns its public URL as a string:
|
||||
|
||||
```tsx
|
||||
import image from './img.png'
|
||||
|
||||
export default function App() {
|
||||
return <img src={image} />
|
||||
}
|
||||
```
|
||||
|
||||
With Next.js, static image imports return an object. The object can then be used directly with the Next.js [`<Image>` component](/docs/app/api-reference/components/image), or you can use the object's `src` property with your existing `<img>` tag.
|
||||
|
||||
The `<Image>` component has the added benefits of [automatic image optimization](/docs/app/api-reference/components/image). The `<Image>` component automatically sets the `width` and `height` attributes of the resulting `<img>` based on the image's dimensions. This prevents layout shifts when the image loads. However, this can cause issues if your app contains images with only one of their dimensions being styled without the other styled to `auto`. When not styled to `auto`, the dimension will default to the `<img>` dimension attribute's value, which can cause the image to appear distorted.
|
||||
|
||||
Keeping the `<img>` tag will reduce the amount of changes in your application and prevent the above issues. You can then optionally later migrate to the `<Image>` component to take advantage of optimizing images by [configuring a loader](/docs/app/api-reference/components/image#loader), or moving to the default Next.js server which has automatic image optimization.
|
||||
|
||||
**Convert absolute import paths for images imported from `/public` into relative imports:**
|
||||
|
||||
```tsx
|
||||
// Before
|
||||
import logo from '/logo.png'
|
||||
|
||||
// After
|
||||
import logo from '../public/logo.png'
|
||||
```
|
||||
|
||||
**Pass the image `src` property instead of the whole image object to your `<img>` tag:**
|
||||
|
||||
```tsx
|
||||
// Before
|
||||
<img src={logo} />
|
||||
|
||||
// After
|
||||
<img src={logo.src} />
|
||||
```
|
||||
|
||||
Alternatively, you can reference the public URL for the image asset based on the filename. For example, `public/logo.png` will serve the image at `/logo.png` for your application, which would be the `src` value.
|
||||
|
||||
> **Warning:** If you're using TypeScript, you might encounter type errors when accessing the `src` property. To fix them, you need to add `next-env.d.ts` to the [`include` array](https://www.typescriptlang.org/tsconfig#include) of your `tsconfig.json` file. Next.js will automatically generate this file when you run your application on step 9.
|
||||
|
||||
### Step 9: Migrate Environment Variables
|
||||
|
||||
Next.js supports [environment variables](/docs/app/guides/environment-variables) similarly to CRA but **requires** a `NEXT_PUBLIC_` prefix for any variable you want to expose in the browser.
|
||||
|
||||
The main difference is the prefix used to expose environment variables on the client-side. Change all environment variables with the `REACT_APP_` prefix to `NEXT_PUBLIC_`.
|
||||
|
||||
### Step 10: Update Scripts in `package.json`
|
||||
|
||||
Update your `package.json` scripts to use Next.js commands. Also, add `.next` and `next-env.d.ts` to your `.gitignore`:
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"build": "next build",
|
||||
"start": "npx serve@latest ./build"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```txt filename=".gitignore"
|
||||
# ...
|
||||
.next
|
||||
next-env.d.ts
|
||||
```
|
||||
|
||||
Now you can run:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm run dev
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn dev
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun dev
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000). You should see your application now running on Next.js (in SPA mode).
|
||||
|
||||
### Step 11: Clean Up
|
||||
|
||||
You can now remove artifacts that are specific to Create React App:
|
||||
|
||||
- `public/index.html`
|
||||
- `src/index.tsx`
|
||||
- `src/react-app-env.d.ts`
|
||||
- The `reportWebVitals` setup
|
||||
- The `react-scripts` dependency (uninstall it from `package.json`)
|
||||
|
||||
## Additional Considerations
|
||||
|
||||
### Using a Custom `homepage` in CRA
|
||||
|
||||
If you used the `homepage` field in your CRA `package.json` to serve the app under a specific subpath, you can replicate that in Next.js using the [`basePath` configuration](/docs/app/api-reference/config/next-config-js/basePath) in `next.config.ts`:
|
||||
|
||||
```ts filename="next.config.ts"
|
||||
import { NextConfig } from 'next'
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
basePath: '/my-subpath',
|
||||
// ...
|
||||
}
|
||||
|
||||
export default nextConfig
|
||||
```
|
||||
|
||||
### Handling a Custom `Service Worker`
|
||||
|
||||
If you used CRA’s service worker (e.g., `serviceWorker.js` from `create-react-app`), you can learn how to create [Progressive Web Applications (PWAs)](/docs/app/guides/progressive-web-apps) with Next.js.
|
||||
|
||||
### Proxying API Requests
|
||||
|
||||
If your CRA app used the `proxy` field in `package.json` to forward requests to a backend server, you can replicate this with [Next.js rewrites](/docs/app/api-reference/config/next-config-js/rewrites) in `next.config.ts`:
|
||||
|
||||
```ts filename="next.config.ts"
|
||||
import { NextConfig } from 'next'
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
async rewrites() {
|
||||
return [
|
||||
{
|
||||
source: '/api/:path*',
|
||||
destination: 'https://your-backend.com/:path*',
|
||||
},
|
||||
]
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Webpack
|
||||
|
||||
If you had a custom webpack or Babel configuration in CRA, you can extend Next.js’s config in `next.config.ts`:
|
||||
|
||||
```ts filename="next.config.ts"
|
||||
import { NextConfig } from 'next'
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
webpack: (config, { isServer }) => {
|
||||
// Modify the webpack config here
|
||||
return config
|
||||
},
|
||||
}
|
||||
|
||||
export default nextConfig
|
||||
```
|
||||
|
||||
> **Note**: This will require using Webpack by adding `--webpack` to your `dev` script.
|
||||
|
||||
### TypeScript Setup
|
||||
|
||||
Next.js automatically sets up TypeScript if you have a `tsconfig.json`. Make sure `next-env.d.ts` is listed in your `tsconfig.json` `include` array:
|
||||
|
||||
```json
|
||||
{
|
||||
"include": ["next-env.d.ts", "app/**/*", "src/**/*"]
|
||||
}
|
||||
```
|
||||
|
||||
## Bundler Compatibility
|
||||
|
||||
Create React App uses webpack for bundling. Next.js now defaults to [Turbopack](/docs/app/api-reference/config/next-config-js/turbopack) for faster local development:
|
||||
|
||||
```bash
|
||||
next dev # Uses Turbopack by default
|
||||
```
|
||||
|
||||
To use Webpack instead (similar to CRA):
|
||||
|
||||
```bash
|
||||
next dev --webpack
|
||||
```
|
||||
|
||||
You can still provide a [custom webpack configuration](/docs/app/api-reference/config/next-config-js/webpack) if you need to migrate advanced webpack settings from CRA.
|
||||
|
||||
## Next Steps
|
||||
|
||||
If everything worked, you now have a functioning Next.js application running as a single-page application. You aren’t yet leveraging Next.js features like server-side rendering or file-based routing, but you can now do so incrementally:
|
||||
|
||||
- **Migrate from React Router** to the [Next.js App Router](/docs/app) for:
|
||||
- Automatic code splitting
|
||||
- [Streaming server rendering](/docs/app/api-reference/file-conventions/loading)
|
||||
- [React Server Components](/docs/app/getting-started/server-and-client-components)
|
||||
- **Optimize images** with the [`<Image>` component](/docs/app/api-reference/components/image)
|
||||
- **Optimize fonts** with [`next/font`](/docs/app/api-reference/components/font)
|
||||
- **Optimize third-party scripts** with the [`<Script>` component](/docs/app/guides/scripts)
|
||||
- **Enable ESLint** with Next.js [recommended rules](/docs/app/api-reference/config/eslint#setup-eslint)
|
||||
|
||||
> **Note**: Using a static export (`output: 'export'`) [does not currently support](https://github.com/vercel/next.js/issues/54393) the `useParams` hook or other server features. To use all Next.js features, remove `output: 'export'` from your `next.config.ts`.
|
||||
+614
@@ -0,0 +1,614 @@
|
||||
---
|
||||
title: How to migrate from Vite to Next.js
|
||||
nav_title: Vite
|
||||
description: Learn how to migrate your existing React application from Vite to Next.js.
|
||||
---
|
||||
|
||||
This guide will help you migrate an existing Vite application to Next.js.
|
||||
|
||||
## Why Switch?
|
||||
|
||||
There are several reasons why you might want to switch from Vite to Next.js:
|
||||
|
||||
### Slow initial page loading time
|
||||
|
||||
If you have built your application with the [default Vite plugin for React](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react), your application is a purely client-side application. Client-side only applications, also known as single-page applications (SPAs), often experience slow initial page loading time. This happens due to a couple of reasons:
|
||||
|
||||
1. The browser needs to wait for the React code and your entire application bundle to download and run before your code is able to send requests to load some data.
|
||||
2. Your application code grows with every new feature and extra dependency you add.
|
||||
|
||||
### No automatic code splitting
|
||||
|
||||
The previous issue of slow loading times can be somewhat managed with code splitting. However, if you try to do code splitting manually, you'll often make performance worse. It's easy to inadvertently introduce network waterfalls when code-splitting manually. Next.js provides automatic code splitting built into its router.
|
||||
|
||||
### Network waterfalls
|
||||
|
||||
A common cause of poor performance occurs when applications make sequential client-server requests to fetch data. One common pattern for data fetching in an SPA is to initially render a placeholder, and then fetch data after the component has mounted. Unfortunately, this means that a child component that fetches data can't start fetching until the parent component has finished loading its own data.
|
||||
|
||||
While fetching data on the client is supported with Next.js, it also gives you the option to shift data fetching to the server, which can eliminate client-server waterfalls.
|
||||
|
||||
### Fast and intentional loading states
|
||||
|
||||
With built-in support for [streaming through React Suspense](/docs/app/getting-started/linking-and-navigating#streaming), you can be more intentional about which parts of your UI you want to load first and in what order without introducing network waterfalls.
|
||||
|
||||
This enables you to build pages that are faster to load and eliminate [layout shifts](https://vercel.com/blog/how-core-web-vitals-affect-seo).
|
||||
|
||||
### Choose the data fetching strategy
|
||||
|
||||
Depending on your needs, Next.js allows you to choose your data fetching strategy on a page and component basis. You can decide to fetch at build time, at request time on the server, or on the client. For example, you can fetch data from your CMS and render your blog posts at build time, which can then be efficiently cached on a CDN.
|
||||
|
||||
### Proxy
|
||||
|
||||
[Next.js Proxy](/docs/app/api-reference/file-conventions/proxy) allows you to run code on the server before a request is completed. This is especially useful to avoid having a flash of unauthenticated content when the user visits an authenticated-only page by redirecting the user to a login page. The proxy is also useful for experimentation and [internationalization](/docs/app/guides/internationalization).
|
||||
|
||||
### Built-in Optimizations
|
||||
|
||||
[Images](/docs/app/api-reference/components/image), [fonts](/docs/app/api-reference/components/font), and [third-party scripts](/docs/app/guides/scripts) often have significant impact on an application's performance. Next.js comes with built-in components that automatically optimize those for you.
|
||||
|
||||
## Migration Steps
|
||||
|
||||
Our goal with this migration is to get a working Next.js application as quickly as possible, so that
|
||||
you can then adopt Next.js features incrementally. To begin with, we'll keep it as a purely
|
||||
client-side application (SPA) without migrating your existing router. This helps minimize the
|
||||
chances of encountering issues during the migration process and reduces merge conflicts.
|
||||
|
||||
### Step 1: Install the Next.js Dependency
|
||||
|
||||
The first thing you need to do is to install `next` as a dependency:
|
||||
|
||||
```bash package="pnpm"
|
||||
pnpm add next@latest
|
||||
```
|
||||
|
||||
```bash package="npm"
|
||||
npm install next@latest
|
||||
```
|
||||
|
||||
```bash package="yarn"
|
||||
yarn add next@latest
|
||||
```
|
||||
|
||||
```bash package="bun"
|
||||
bun add next@latest
|
||||
```
|
||||
|
||||
### Step 2: Create the Next.js Configuration File
|
||||
|
||||
Create a `next.config.mjs` at the root of your project. This file will hold your
|
||||
[Next.js configuration options](/docs/app/api-reference/config/next-config-js).
|
||||
|
||||
```js filename="next.config.mjs"
|
||||
/** @type {import('next').NextConfig} */
|
||||
const nextConfig = {
|
||||
output: 'export', // Outputs a Single-Page Application (SPA).
|
||||
distDir: './dist', // Changes the build output directory to `./dist/`.
|
||||
}
|
||||
|
||||
export default nextConfig
|
||||
```
|
||||
|
||||
> **Good to know:** You can use either `.js` or `.mjs` for your Next.js configuration file.
|
||||
|
||||
### Step 3: Update TypeScript Configuration
|
||||
|
||||
If you're using TypeScript, you need to update your `tsconfig.json` file with the following changes
|
||||
to make it compatible with Next.js. If you're not using TypeScript, you can skip this step.
|
||||
|
||||
1. Remove the [project reference](https://www.typescriptlang.org/tsconfig#references) to `tsconfig.node.json`
|
||||
2. Add `./dist/types/**/*.ts` and `./next-env.d.ts` to the [`include` array](https://www.typescriptlang.org/tsconfig#include)
|
||||
3. Add `./node_modules` to the [`exclude` array](https://www.typescriptlang.org/tsconfig#exclude)
|
||||
4. Add `{ "name": "next" }` to the [`plugins` array in `compilerOptions`](https://www.typescriptlang.org/tsconfig#plugins): `"plugins": [{ "name": "next" }]`
|
||||
5. Set [`esModuleInterop`](https://www.typescriptlang.org/tsconfig#esModuleInterop) to `true`: `"esModuleInterop": true`
|
||||
6. Set [`jsx`](https://www.typescriptlang.org/tsconfig#jsx) to `react-jsx`: `"jsx": "react-jsx"`
|
||||
7. Set [`allowJs`](https://www.typescriptlang.org/tsconfig#allowJs) to `true`: `"allowJs": true`
|
||||
8. Set [`forceConsistentCasingInFileNames`](https://www.typescriptlang.org/tsconfig#forceConsistentCasingInFileNames) to `true`: `"forceConsistentCasingInFileNames": true`
|
||||
9. Set [`incremental`](https://www.typescriptlang.org/tsconfig#incremental) to `true`: `"incremental": true`
|
||||
|
||||
Here's an example of a working `tsconfig.json` with those changes:
|
||||
|
||||
```json filename="tsconfig.json"
|
||||
{
|
||||
"compilerOptions": {
|
||||
"target": "ES2020",
|
||||
"useDefineForClassFields": true,
|
||||
"lib": ["ES2020", "DOM", "DOM.Iterable"],
|
||||
"module": "ESNext",
|
||||
"esModuleInterop": true,
|
||||
"skipLibCheck": true,
|
||||
"moduleResolution": "bundler",
|
||||
"allowImportingTsExtensions": true,
|
||||
"resolveJsonModule": true,
|
||||
"isolatedModules": true,
|
||||
"noEmit": true,
|
||||
"jsx": "react-jsx",
|
||||
"strict": true,
|
||||
"noUnusedLocals": true,
|
||||
"noUnusedParameters": true,
|
||||
"noFallthroughCasesInSwitch": true,
|
||||
"allowJs": true,
|
||||
"forceConsistentCasingInFileNames": true,
|
||||
"incremental": true,
|
||||
"plugins": [{ "name": "next" }]
|
||||
},
|
||||
"include": ["./src", "./dist/types/**/*.ts", "./next-env.d.ts"],
|
||||
"exclude": ["./node_modules"]
|
||||
}
|
||||
```
|
||||
|
||||
You can find more information about configuring TypeScript on the
|
||||
[Next.js docs](/docs/app/api-reference/config/typescript#ide-plugin).
|
||||
|
||||
### Step 4: Create the Root Layout
|
||||
|
||||
A Next.js [App Router](/docs/app) application must include a
|
||||
[root layout](/docs/app/api-reference/file-conventions/layout#root-layout)
|
||||
file, which is a [React Server Component](/docs/app/getting-started/server-and-client-components)
|
||||
that will wrap all pages in your application. This file is defined at the top level of the `app`
|
||||
directory.
|
||||
|
||||
The closest equivalent to the root layout file in a Vite application is the
|
||||
[`index.html` file](https://vitejs.dev/guide/#index-html-and-project-root), which contains your
|
||||
`<html>`, `<head>`, and `<body>` tags.
|
||||
|
||||
In this step, you'll convert your `index.html` file into a root layout file:
|
||||
|
||||
1. Create a new `app` directory in your `src` folder.
|
||||
2. Create a new `layout.tsx` file inside that `app` directory:
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return '...'
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export default function RootLayout({ children }) {
|
||||
return '...'
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**: `.js`, `.jsx`, or `.tsx` extensions can be used for Layout files.
|
||||
|
||||
3. Copy the content of your `index.html` file into the previously created `<RootLayout>` component while
|
||||
replacing the `body.div#root` and `body.script` tags with `<div id="root">{children}</div>`:
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<link rel="icon" type="image/svg+xml" href="/icon.svg" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>My App</title>
|
||||
<meta name="description" content="My App is a..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<link rel="icon" type="image/svg+xml" href="/icon.svg" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>My App</title>
|
||||
<meta name="description" content="My App is a..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
4. Next.js already includes by default the
|
||||
[meta charset](https://developer.mozilla.org/docs/Web/HTML/Element/meta#charset) and
|
||||
[meta viewport](https://developer.mozilla.org/docs/Web/HTML/Viewport_meta_tag) tags, so you
|
||||
can safely remove those from your `<head>`:
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<link rel="icon" type="image/svg+xml" href="/icon.svg" />
|
||||
<title>My App</title>
|
||||
<meta name="description" content="My App is a..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<link rel="icon" type="image/svg+xml" href="/icon.svg" />
|
||||
<title>My App</title>
|
||||
<meta name="description" content="My App is a..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
5. Any [metadata files](/docs/app/getting-started/metadata-and-og-images#file-based-metadata)
|
||||
such as `favicon.ico`, `icon.png`, `robots.txt` are automatically added to the application
|
||||
`<head>` tag as long as you have them placed into the top level of the `app` directory. After
|
||||
moving
|
||||
[all supported files](/docs/app/getting-started/metadata-and-og-images#file-based-metadata)
|
||||
into the `app` directory you can safely delete their `<link>` tags:
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<title>My App</title>
|
||||
<meta name="description" content="My App is a..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<head>
|
||||
<title>My App</title>
|
||||
<meta name="description" content="My App is a..." />
|
||||
</head>
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
6. Finally, Next.js can manage your last `<head>` tags with the
|
||||
[Metadata API](/docs/app/getting-started/metadata-and-og-images). Move your final metadata
|
||||
info into an exported
|
||||
[`metadata` object](/docs/app/api-reference/functions/generate-metadata#metadata-object):
|
||||
|
||||
```tsx filename="app/layout.tsx" switcher
|
||||
import type { Metadata } from 'next'
|
||||
|
||||
export const metadata: Metadata = {
|
||||
title: 'My App',
|
||||
description: 'My App is a...',
|
||||
}
|
||||
|
||||
export default function RootLayout({
|
||||
children,
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
}) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/layout.js" switcher
|
||||
export const metadata = {
|
||||
title: 'My App',
|
||||
description: 'My App is a...',
|
||||
}
|
||||
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html lang="en">
|
||||
<body>
|
||||
<div id="root">{children}</div>
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
With the above changes, you shifted from declaring everything in your `index.html` to using Next.js'
|
||||
convention-based approach built into the framework
|
||||
([Metadata API](/docs/app/getting-started/metadata-and-og-images)). This approach enables you
|
||||
to more easily improve your SEO and web shareability of your pages.
|
||||
|
||||
### Step 5: Create the Entrypoint Page
|
||||
|
||||
On Next.js you declare an entrypoint for your application by creating a `page.tsx` file. The
|
||||
closest equivalent of this file on Vite is your `main.tsx` file. In this step, you’ll set up the
|
||||
entrypoint of your application.
|
||||
|
||||
1. **Create a `[[...slug]]` directory in your `app` directory.**
|
||||
|
||||
Since in this guide we're aiming first to set up our Next.js as an SPA (Single Page Application), you need your page entrypoint to catch all possible routes of your application. For that, create a new `[[...slug]]` directory in your `app` directory.
|
||||
|
||||
This directory is what is called an [optional catch-all route segment](/docs/app/api-reference/file-conventions/dynamic-routes#optional-catch-all-segments). Next.js uses a file-system based router where folders are used to define routes. This special directory will make sure that all routes of your application will be directed to its containing `page.tsx` file.
|
||||
|
||||
2. **Create a new `page.tsx` file inside the `app/[[...slug]]` directory with the following content:**
|
||||
|
||||
```tsx filename="app/[[...slug]]/page.tsx" switcher
|
||||
import '../../index.css'
|
||||
|
||||
export function generateStaticParams() {
|
||||
return [{ slug: [''] }]
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return '...' // We'll update this
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/[[...slug]]/page.js" switcher
|
||||
import '../../index.css'
|
||||
|
||||
export function generateStaticParams() {
|
||||
return [{ slug: [''] }]
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return '...' // We'll update this
|
||||
}
|
||||
```
|
||||
|
||||
> **Good to know**: `.js`, `.jsx`, or `.tsx` extensions can be used for Page files.
|
||||
|
||||
This file is a [Server Component](/docs/app/getting-started/server-and-client-components). When you run `next build`, the file is prerendered into a static asset. It does _not_ require any dynamic code.
|
||||
|
||||
This file imports our global CSS and tells [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) we are only going to generate one route, the index route at `/`.
|
||||
|
||||
Now, let's move the rest of our Vite application which will run client-only.
|
||||
|
||||
```tsx filename="app/[[...slug]]/client.tsx" switcher
|
||||
'use client'
|
||||
|
||||
import React from 'react'
|
||||
import dynamic from 'next/dynamic'
|
||||
|
||||
const App = dynamic(() => import('../../App'), { ssr: false })
|
||||
|
||||
export function ClientOnly() {
|
||||
return <App />
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/[[...slug]]/client.js" switcher
|
||||
'use client'
|
||||
|
||||
import React from 'react'
|
||||
import dynamic from 'next/dynamic'
|
||||
|
||||
const App = dynamic(() => import('../../App'), { ssr: false })
|
||||
|
||||
export function ClientOnly() {
|
||||
return <App />
|
||||
}
|
||||
```
|
||||
|
||||
This file is a [Client Component](/docs/app/getting-started/server-and-client-components), defined by the `'use client'`
|
||||
directive. Client Components are still [prerendered to HTML](/docs/app/getting-started/server-and-client-components#how-do-server-and-client-components-work-in-nextjs) on the server before being sent to the client.
|
||||
|
||||
Since we want a client-only application to start, we can configure Next.js to disable prerendering from the `App` component down.
|
||||
|
||||
```tsx
|
||||
const App = dynamic(() => import('../../App'), { ssr: false })
|
||||
```
|
||||
|
||||
Now, update your entrypoint page to use the new component:
|
||||
|
||||
```tsx filename="app/[[...slug]]/page.tsx" switcher
|
||||
import '../../index.css'
|
||||
import { ClientOnly } from './client'
|
||||
|
||||
export function generateStaticParams() {
|
||||
return [{ slug: [''] }]
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return <ClientOnly />
|
||||
}
|
||||
```
|
||||
|
||||
```jsx filename="app/[[...slug]]/page.js" switcher
|
||||
import '../../index.css'
|
||||
import { ClientOnly } from './client'
|
||||
|
||||
export function generateStaticParams() {
|
||||
return [{ slug: [''] }]
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return <ClientOnly />
|
||||
}
|
||||
```
|
||||
|
||||
### Step 6: Update Static Image Imports
|
||||
|
||||
Next.js handles static image imports slightly different from Vite. With Vite, importing an image
|
||||
file will return its public URL as a string:
|
||||
|
||||
```tsx filename="App.tsx"
|
||||
import image from './img.png' // `image` will be '/assets/img.2d8efhg.png' in production
|
||||
|
||||
export default function App() {
|
||||
return <img src={image} />
|
||||
}
|
||||
```
|
||||
|
||||
With Next.js, static image imports return an object. The object can then be used directly with the
|
||||
Next.js [`<Image>` component](/docs/app/api-reference/components/image), or you can use the object's
|
||||
`src` property with your existing `<img>` tag.
|
||||
|
||||
The `<Image>` component has the added benefits of
|
||||
[automatic image optimization](/docs/app/api-reference/components/image). The `<Image>`
|
||||
component automatically sets the `width` and `height` attributes of the resulting `<img>` based on
|
||||
the image's dimensions. This prevents layout shifts when the image loads. However, this can cause
|
||||
issues if your app contains images with only one of their dimensions being styled without the other
|
||||
styled to `auto`. When not styled to `auto`, the dimension will default to the `<img>` dimension
|
||||
attribute's value, which can cause the image to appear distorted.
|
||||
|
||||
Keeping the `<img>` tag will reduce the amount of changes in your application and prevent the above
|
||||
issues. You can then optionally later migrate to the `<Image>` component to take advantage of optimizing images by [configuring a loader](/docs/app/api-reference/components/image#loader), or moving to the default Next.js server which has automatic image optimization.
|
||||
|
||||
1. **Convert absolute import paths for images imported from `/public` into relative imports:**
|
||||
|
||||
```tsx
|
||||
// Before
|
||||
import logo from '/logo.png'
|
||||
|
||||
// After
|
||||
import logo from '../public/logo.png'
|
||||
```
|
||||
|
||||
2. **Pass the image `src` property instead of the whole image object to your `<img>` tag:**
|
||||
|
||||
```tsx
|
||||
// Before
|
||||
<img src={logo} />
|
||||
|
||||
// After
|
||||
<img src={logo.src} />
|
||||
```
|
||||
|
||||
Alternatively, you can reference the public URL for the image asset based on the filename. For example, `public/logo.png` will serve the image at `/logo.png` for your application, which would be the `src` value.
|
||||
|
||||
> **Warning:** If you're using TypeScript, you might encounter type errors when accessing the `src`
|
||||
> property. You can safely ignore those for now. They will be fixed by the end of this guide.
|
||||
|
||||
### Step 7: Migrate the Environment Variables
|
||||
|
||||
Next.js has support for `.env`
|
||||
[environment variables](/docs/app/guides/environment-variables)
|
||||
similar to Vite. The main difference is the prefix used to expose environment variables on the
|
||||
client-side.
|
||||
|
||||
- Change all environment variables with the `VITE_` prefix to `NEXT_PUBLIC_`.
|
||||
|
||||
Vite exposes a few built-in environment variables on the special `import.meta.env` object which
|
||||
aren’t supported by Next.js. You need to update their usage as follows:
|
||||
|
||||
- `import.meta.env.MODE` ⇒ `process.env.NODE_ENV`
|
||||
- `import.meta.env.PROD` ⇒ `process.env.NODE_ENV === 'production'`
|
||||
- `import.meta.env.DEV` ⇒ `process.env.NODE_ENV !== 'production'`
|
||||
- `import.meta.env.SSR` ⇒ `typeof window !== 'undefined'`
|
||||
|
||||
Next.js also doesn't provide a built-in `BASE_URL` environment variable. However, you can still
|
||||
configure one, if you need it:
|
||||
|
||||
1. **Add the following to your `.env` file:**
|
||||
|
||||
```bash filename=".env"
|
||||
# ...
|
||||
NEXT_PUBLIC_BASE_PATH="/some-base-path"
|
||||
```
|
||||
|
||||
2. **Set [`basePath`](/docs/app/api-reference/config/next-config-js/basePath) to `process.env.NEXT_PUBLIC_BASE_PATH` in your `next.config.mjs` file:**
|
||||
|
||||
```js filename="next.config.mjs"
|
||||
/** @type {import('next').NextConfig} */
|
||||
const nextConfig = {
|
||||
output: 'export', // Outputs a Single-Page Application (SPA).
|
||||
distDir: './dist', // Changes the build output directory to `./dist/`.
|
||||
basePath: process.env.NEXT_PUBLIC_BASE_PATH, // Sets the base path to `/some-base-path`.
|
||||
}
|
||||
|
||||
export default nextConfig
|
||||
```
|
||||
|
||||
3. **Update `import.meta.env.BASE_URL` usages to `process.env.NEXT_PUBLIC_BASE_PATH`**
|
||||
|
||||
### Step 8: Update Scripts in `package.json`
|
||||
|
||||
You should now be able to run your application to test if you successfully migrated to Next.js. But
|
||||
before that, you need to update your `scripts` in your `package.json` with Next.js related commands,
|
||||
and add `.next` and `next-env.d.ts` to your `.gitignore`:
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"build": "next build",
|
||||
"start": "next start"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```txt filename=".gitignore"
|
||||
# ...
|
||||
.next
|
||||
next-env.d.ts
|
||||
dist
|
||||
```
|
||||
|
||||
Now run `npm run dev`, and open [`http://localhost:3000`](http://localhost:3000). You should see your application now running on Next.js.
|
||||
|
||||
> **Example:** Check out [this pull request](https://github.com/inngest/vite-to-nextjs/pull/1) for a
|
||||
> working example of a Vite application migrated to Next.js.
|
||||
|
||||
### Step 9: Clean Up
|
||||
|
||||
You can now clean up your codebase from Vite related artifacts:
|
||||
|
||||
- Delete `main.tsx`
|
||||
- Delete `index.html`
|
||||
- Delete `vite-env.d.ts`
|
||||
- Delete `tsconfig.node.json`
|
||||
- Delete `vite.config.ts`
|
||||
- Uninstall Vite dependencies
|
||||
|
||||
## Next Steps
|
||||
|
||||
If everything went according to plan, you now have a functioning Next.js application running as a
|
||||
single-page application. However, you aren't yet taking advantage of most of Next.js' benefits, but
|
||||
you can now start making incremental changes to reap all the benefits. Here's what you might want to
|
||||
do next:
|
||||
|
||||
- Migrate from React Router to the [Next.js App Router](/docs/app) to get:
|
||||
- Automatic code splitting
|
||||
- [Streaming Server-Rendering](/docs/app/api-reference/file-conventions/loading)
|
||||
- [React Server Components](/docs/app/getting-started/server-and-client-components)
|
||||
- [Optimize images with the `<Image>` component](/docs/app/api-reference/components/image)
|
||||
- [Optimize fonts with `next/font`](/docs/app/api-reference/components/font)
|
||||
- [Optimize third-party scripts with the `<Script>` component](/docs/app/guides/scripts)
|
||||
- [Update your ESLint configuration to support Next.js rules](/docs/app/api-reference/config/eslint)
|
||||
+4
@@ -0,0 +1,4 @@
|
||||
---
|
||||
title: Migrating
|
||||
description: Learn how to migrate from popular frameworks to Next.js
|
||||
---
|
||||
Reference in New Issue
Block a user