A practical Guide - Migrating to Next.js App Router

With the release of the Next.js App Router, many developers are eager to migrate their existing projects. In this post, I’ll share my experience migrating a project to the Next.js App Router, including key challenges, changes, and how you can make the process smoother.

It's an incremental approach, you can use the page router and app router simultaneously.

Why Migrate to the Next.js App Router?

The App Router introduces several advantages:

• Improved Routing: Cleaner file-system-based routing.
• Server-Side Rendering (SSR) Enhancements: More efficient handling of server-side data.
• Meta Handling: Simplified SEO management.
• Improved Performance: Built-in optimizations for various components.

By migrating, you can future-proof your application to take advantage of the latest Next.js features.

Steps to Migrate to the App Router

• Update Dependencies

The first step is to ensure your Next.js and related dependencies are up to date. Run the following commands to install the latest versions of Next.js and React:

npm install next@latest react@latest react-dom@latest
npm install -D eslint-config-next@latest

• Structure the App Folder

The App Router relies on the new app directory for managing routes, metadata, and layouts. Here's how to structure it:

App Folder: Move your pages into the app folder. Each route now has its own dedicated folder containing a page.tsx file.

Layouts: Add a layout.tsx file to define layouts for specific sections of your app. This is particularly useful for handling shared components like navigation bars or footers.

• Router Changes

One of the most significant changes is the replacement of next/router with next/navigation for routing and navigation functionality.

Replace all next/router imports with next/navigation.
Update functions like useRouter with new equivalents, such as usePathname, useSearchParams, and useRouter() where appropriate.

• Refactor Server-Side Code

getServerSideProps and getStaticProps are deprecated in the App Router.
Use async server components or server actions for data fetching in server-side pages.

export async function getData() {
  const res = await fetch('https://getData.com/data');
  return res.json();
}

• Handling Client-Side Components

Client components:
Any component that uses React hooks, browser APIs, or user interactions must be marked with 'use client'. This tells Next.js to render them on the client side.

Server Components:
Any component that does not require interaction with the browser can remain as a server component. These are more efficient since they avoid shipping unnecessary JavaScript to the client.

• Handling External Libraries

If you are using external libraries like React Query, AntDesign or framer etc. You need to update them and make changes as needed. Can't include all the changes in this blog. Although changes are mentioned in their documentation.

Common Challenges During Migration

• Router Event Handling:

With the change from next/router to next/navigation, handling router events might require a different approach.
Ensure that you update any router event listeners or hooks accordingly.

• Layout Shift Issues:

When migrating pages with complex layouts (especially those with animations), you may notice layout shifts. Add placeholder or keep proper alignment on server-side itself to prevent layout shifts.

• Image and Link Component Updates:

The App Router introduces changes to the Image and Link components.
Use codemods to automatically update components.
For the Image component, remove deprecated attributes like responsive.

• Animations

Animation related components like framer, swiper, and lootie files need to be kept at the client side.

Conclusion

Migrating to the Next.js App Router comes with its challenges but also with significant improvements in performance, scalability, and flexibility. By breaking down the migration into manageable sections (app-level, page-level, and feature updates), I was able to tackle each change systematically.

Let me know if you have any questions or tips from your own migrations!

The above is the detailed content of A practical Guide - Migrating to Next.js App Router. For more information, please follow other related articles on the PHP Chinese website!