[KM] App Router vs Pages Router in Next.js (撰寫 part 4)

[godmmt]

文章位置: https://github.com/CAFECA-IO/KnowledgeManagement/blob/master/NextJs/app-router-vs-pages-router-in-next-js.md

此張 issue 待完成任務

• [x] 定稿：Rendering——App Router 渲染概念（伺服器元件／客戶端元件）
• [x] 資料搜集＆研究、撰寫草稿：Routing——路由差異
• [x] 補充我們團隊現有的資料夾結構慣例在「建立 Next.js 專案」章節
• [x] 更新：初步認識 Next.js 路由架構——App Router 與 Pages Router
• [x] 新增：「Routing——路由差異」之兩版本路由系統的路由詳細說明 (部分完成)

[godmmt]

(更新) 文章架構

• 前言
  • 初步認識 Next.js
  • 1.React vs Next.js：函式庫與框架
  • 2.為什麼選擇 Next.js
  • 3.Next.js 特色
  • Next.js Router System 路由系統
• 專案建立——資料夾結構差異
  • 建立 Next.js 專案
  • Page Router 資料夾結構
  • App Router 資料夾結構
• Rendering——渲染的四種方式、路由系統對四種渲染的應用差異
  • 了解 Next.js 中的渲染方法：CSR vs SSR vs SSG vs ISR
  • 1. 客戶端渲染 (Client-side Rendering, CSR)
  • 2. 伺服器端渲染 (Server-side Rendering, SSR)
  • 3. 靜態網站生成 (Static Site Generation, SSG)
  • 4. 增量靜態再生 (Incremental Static Regeneration, ISR)
  • Page Router 處理 4 種渲染的方式
  • 1. 客戶端渲染 (CSR)
  • 2. 伺服器端渲染 (SSR)
  • 3. 靜態網站生成 (SSG)
  • 4. 增量靜態再生 (ISR)
  • Page Router 處理 4 種渲染的方式總結
  • App Router 處理 4 種渲染的方式
  • 1. 客戶端渲染 (CSR)
  • 2. 伺服器端渲染 (SSR)
  • 3. 靜態網站生成 (SSG)
  • 4. 增量靜態再生 (ISR)
  • App Router 處理 4 種渲染的方式總結
• Rendering——App Router 渲染概念
  • 1. 伺服器元件（React Server Component, RSC）
  • 伺服器渲染的好處
  • 在 Next.js 中使用伺服器元件
  • 伺服器元件如何渲染？
  • 伺服器渲染策略—— 1. 靜態渲染（預設）
  • 伺服器渲染策略—— 2. 動態渲染
  • 伺服器渲染策略—— 3. 串流
  • 2. 客戶端元件（Client Component）
  • 客戶端渲染的好處
  • 在 Next.js 中使用客戶端元件
  • 客戶端元件如何渲染？
• Routing——路由使用差異
• Data Fetching——資料獲取差異
• 逐步遷移的方式
• 實作——App Router
• 結論
  • 條列式整理差異
  • 適用情境
  • 對於專案的建議
• 參考資料

[godmmt]

草稿：Routing——路由差異

要理解 Next.js 中 App Router 和 Page Router 在 Routing 上的差異，我們可以根據「使用 App Router」部分的功能來進行比較。這有助於釐清哪些功能是各自獨有的，以及哪一方可能在某些方面更具優勢。

1. 定義路由（Defining Routes）

• App Router：路由是透過 /app 目錄中的資料夾結構定義的。目錄結構直接對應到 URL 路徑，不依賴於檔案命名規範。
• Page Router：路由是在 /pages 目錄中定義的。此目錄中的每個檔案自動成為一個路由，且資料夾結構決定動態路由。這種方法簡單明瞭，但在組織路由方面彈性較小。

優勢：App Router 提供了基於巢狀目錄和檔案的更靈活的路由結構，這有助於更好地控制複雜的路由需求。（但也有人覺得這樣做反而更複雜，並沒有比 Page Router 更直覺）

2. 佈局和模板（Layouts and Templates）

• App Router：支援內建佈局和模板，允許巢狀佈局和可重用的模板應用於不同路由。
• Page Router：沒有支援內建的佈局和模板，需要在每個頁面手動實作佈局元件。

優勢：App Router 擁有內建支援佈局和模板的優勢，減少程式碼的重複性和簡化佈局管理。（但如果頁面的佈局變化不大，這方面的優勢就不明顯）

3. 連結和導航（Linking and Navigating）

• App Router：使用 Link 元件進行客戶端導航，與 Page Router 相似，但受益於內建的優化功能，可能更好地與 App Router 中的元件層次結構配合。
• Page Router：同樣使用 Link 元件進行客戶端導航，對大多數使用情況來說是直接有效的。

優勢：兩者在這方面的功能類似，但 App Router 可能因其巢狀結構而在先進路由功能的無縫整合方面佔據優勢。

4. 錯誤處理（Error Handling）

• App Router：透過巢狀錯誤邊界支援進階錯誤處理，允許對應用程式的不同部分進行更精細的錯誤控制。
• Page Router：錯誤處理通常涉及建立自訂的 _error.js 頁面來進行全域錯誤處理，或使用 getInitialProps 在頁面層級捕獲錯誤。

優勢：App Router 提供更細粒度的錯誤處理，讓開發人員可以將錯誤隔離到特定的路由或元件。

5. 載入 UI 和串流（Loading UI and Streaming）

• App Router：提供對載入狀態和串流的進階支援，透過允許部分 UI 漸進式載入來改善使用者體驗。
• Page Router：載入狀態通常是使用 React 的 useState 或 useEffect 手動處理的。沒有內建的串流支援。

優勢：App Router 更適合需要複雜載入策略和串流支援的應用程式。

6. 重新導向（Redirecting）

• App Router：由於其靈活的路由結構，支援更複雜的重新導向邏輯。可以針對每個路由或一組路由配置重新導向。
• Page Router：重新導向通常在 next.config.js 中使用 redirects 配置，或在個別頁面元件內部處理。

優勢：App Router 提供更多重新導向的彈性和控制。

7. 路由分組（Route Groups）

• App Router：允許分組路由以便更好地組織和共享路由配置。
• Page Router：不支援路由分組。路由是單獨定義在 /pages 目錄內。

優勢：App Router 在將路由分組以便共享配置方面有明顯優勢。

8. 專案組織（Project Organization）

• App Router：鼓勵更模組化和有組織的檔案結構，將相關的元件、路由和佈局組合在一起。
• Page Router：具有較扁平的檔案結構，所有路由都在 /pages 目錄中定義。

優勢：App Router 更適合大型應用程式的組織。

9. 動態路由（Dynamic Routes）

• App Router：透過目錄結構中的 [param] 語法支援動態路由，並且可以處理更複雜的巢狀動態路由。
• Page Router：同樣支援動態路由，使用 /pages 目錄中的 [param].js 檔案。

優勢：兩者皆支援動態路由，但 App Router 可能在支援巢狀動態路由方面更具優勢。

10. 平行路由（Parallel Routes）

• App Router：原生支援平行路由，允許同時渲染多個路由。
• Page Router：不直接支援平行路由；要實現類似效果，需要更複雜的自訂實作。

優勢：App Router 原生支援平行路由，對需要同時渲染多個路由的複雜應用程式有利。

11. 攔截路由（Intercepting Routes）

• App Router：允許攔截路由以進行自訂邏輯或處理。
• Page Router：沒有直接的路由攔截概念。類似的功能需要透過中介軟體或自訂元件手動實作。

優勢：App Router 提供更多彈性，具有內建的路由攔截功能。

12. 路由處理程式（Route Handlers）

• App Router：支援自訂路由處理程式，可以管理路由或 HTTP 方法的特定邏輯。
• Page Router：不直接支援路由處理程式；處理邏輯通常嵌入在頁面元件中。

優勢：App Router 提供更細粒度的控制，使用路由處理程式。

13. 中介軟體（Middleware）

• App Router：完全支援中介軟體功能來處理請求、修改響應以及在渲染前執行動作。
• Page Router：也支援中介軟體，但通常需要更多配置，因為中介軟體是在 /pages/_middleware.js 檔案中聲明的。

優勢：兩者皆支援中介軟體，但 App Router 可能因其路由結構而更無縫整合。

14. 國際化（Internationalization）

• App Router：原生支援國際化 (i18n)，使處理多語言內容更容易。
• Page Router：也支援國際化，但通常需要在 next.config.js 中進行更多手動設置。

優勢：App Router 在國際化方面可能提供更整合的體驗。

在 Routing 上的差異兩種路由系統的主要差異與優勢總結

• App Router 獨有功能：進階錯誤處理、載入 UI 和串流、路由分組、平行路由、攔截路由和路由處理程式。
• Page Router 獨有功能：簡單易用，學習曲線較低，適合基本的路由需求。
• App Router 優勢：提供更多彈性，適合大型應用程式，並支援像是串流、平行路由和錯誤邊界等進階功能。
• Page Router 優勢：設置簡單，路由邏輯直覺，適合小型到中型專案。

App Router 通常更強大且靈活，適合需要精細的路由控制和狀態管理的複雜現代應用程式。Page Router 則是適合簡單路由需求的專案。

[godmmt]

took 4.5 hours

remain 3.5

[godmmt]

《Routing——路由差異》要再定稿，補充與程式碼實作有關的詳細說明

[godmmt]

• [x] 補充我們團隊現有的資料夾結構慣例（我們使用 Page Router 路由系統）

[godmmt]

補充我們團隊現有的資料夾結構慣例在「建立 Next.js 專案」章節

更新內容如下：

建立 Next.js 專案

首先在終端輸入指令 npx create-next-app 建立 Next.js 專案。

接著會依序出現下列幾個提問，分別如下：

What is your project named? my-app
// 專案名稱，格式需為英文小寫

Would you like to use TypeScript? No / Yes
// 是否支援 TypeScript

Would you like to use ESLint? No / Yes
// 是否使用 ESLint（用來規範 Coding Style 的套件）

Would you like to use Tailwind CSS? No / Yes
// 是否使用 Tailwind CSS

Would you like to use `src/` directory? No / Yes
// 是否外加一層 src 資料夾 (會新增一個 src 資料夾，除了 public 資料夾外，所有檔案都會放在 src 資料夾底下)

Would you like to use App Router? (recommended) No / Yes
// 是否使用 App Router

Would you like to customize the default import alias (@/*)? No / Yes
// 是否自訂 alias 調整預設的 baseURL 匯入路徑

What import alias would you like configured? @/*
// alias 預設使用 @ 是否修改

在 Would you like to use App Router? (recommended) No / Yes 這個步驟選擇 Yes，即可選擇 App Router 路由系統；若選擇 No 則會選擇 Page Router 路由系統。

初始專案架構主要分成以下三大類：（選擇使用 App Router 的情況）

• app 資料夾：放置 components、pages 與 api 等檔案
  • layout.tsx：在多個頁面之間定義共用 UI，其狀態將會被保存，如：nav、header、footer 等元件
  • page.tsx：在資料夾底下需包含 page.tsx 檔案，才會被定義為一個 route segment，如：app/blog/page.tsx
  • globals.css：定義全域樣式
• public 資料夾：放置靜態檔案，如圖片等
  • 需要引入 /public/next.svg 檔案時，路徑可直接指向 /next.svg
• 各類設定檔：包含 next.config.js、tsconfig.json、package.json 等用於設定專案配置的檔案

注意：如果是選擇使用 App Router 來建立專案的話，就會預設出現一個 app 資料夾；而如果使用 Page Router 就會預設出現一個 pages 資料夾。

所以如果是選擇使用 Page Router 的話，也是會出現類似上述的資料夾結構。只是就不會有 app 資料夾，而是會出現 pages 資料夾。

在 pages 資料夾內會用來放置所有頁面元件（每個檔案會成為一個路由），同時我們會特別建立一個 components 資料夾專門用來放置非頁面元件。這個 components 資料夾是我們自己建立的，並不是 Next.js 預設的資料夾，我們通常會放在 /src 資料夾底下。

這裡提供我們團隊的資料夾結構慣例：

└── public
└── src
    ├── components
    ├── constants
    ├── contexts
    ├── interfaces
    ├── lib
    ├── locales
    ├── pages
    ├── styles
    └── ... other folders
└── config files

接下來會介紹兩個路由系統所提供的資料夾 app 與 pages 各別所對應的路由定義規則。

[godmmt]

更新: 將「Next.js Router System 路由系統」改為「初步認識 Next.js 路由架構——App Router 與 Pages Router」

內容已經重構，更新如下：

---

初步認識 Next.js 路由架構——App Router 與 Pages Router

Next.js 使用基於檔案系統的路由（file-system based router），意思是路由會根據專案的檔案結構自動被定義，不需額外去做設定。

究竟什麼是 App Router 跟 Pages Router 呢？簡單來說，它們是  Next 開發的兩套路由架構。

根據版本不同，Next.js 提供兩種管理頁面路由的方式，分別是舊版本適用的 Pages Router 以及 v13 後推出的 App Router，兩者最明顯的差異在於：

Pages Router :

1. 定義頁面層級的路由
2. 所有元件為 React Client Component（客戶端元件）

App Router :

1. 定義應用程式層級的路由
2. 所有元件預設為 React Server Component（伺服器端元件）

定義路由分為頁面層級和應用程式層級，簡單來說 Pages Router 是在 /pages 目錄中定義的，此目錄中的每個檔案自動成為一個路由；App Router 的路由則是透過 /app 目錄中的資料夾結構定義的。

另外，在 App Router 中所有元件預設為 React Server Component（RSC），意思是由伺服器將 React Component 準備好，再傳給 Client 顯示在畫面上。

而 RSC 的優缺點如下：

優點:

1. 整合後端操作，如存取資料庫（DB）、讀取檔案（File System）
2. 降低資料間的依賴關係，改善請求瀑布流（Waterfall）導致的效能問題
3. 降低 JS Bundle Size 以提升頁面效能

缺點:

1. 無法使用 React Hooks
2. 無法使用瀏覽器 API
3. 無法操作 DOM 事件監聽

面對上述缺點，Next.js 可依照使用情境不同，將元件定義為 Server Component 或 Client Component。舉例來說，當某個元件需要使用 Hooks 管理時，可透過在程式碼開頭加上 'use client' 來標示元件類型，該元件底下的子元件也會自動視為 Client Component。

但也因為如此，相較於 Page Router，新版的 App Router 學習曲線會較高，需瞭解 Server 如何運作，以及判斷哪些元件適合放在 Server 或 Client 端，在使用時須特別注意。

另外，App Router 與 Page Router 是可以並存的，但也是有一些基本的限制，像是兩個目錄不能同時定義一個 router，否則會報錯。官網有提供如何從 Page Router migrate App Router 的教學文章，可以參考如何轉換。

以下章節將會針對 App Router 與 Page Router 的差異進行比較，並介紹 App Router 的幾個重要功能。

[godmmt]

更新： 文章架構

文章架構 (點擊展開)

- 前言 - 初步認識 Next.js - 1.React vs Next.js：函式庫與框架 - 2.為什麼選擇 Next.js - 3.Next.js 特色 - 初步認識 Next.js 路由架構——App Router 與 Pages Router - 專案建立——資料夾結構差異 - 建立 Next.js 專案 - Page Router 資料夾結構 - App Router 資料夾結構 - Rendering——渲染的四種方式、路由系統對四種渲染的應用差異 - 了解 Next.js 中的渲染方法：CSR vs SSR vs SSG vs ISR - 1. 客戶端渲染 (Client-side Rendering, CSR) - 2. 伺服器端渲染 (Server-side Rendering, SSR) - 3. 靜態網站生成 (Static Site Generation, SSG) - 4. 增量靜態再生 (Incremental Static Regeneration, ISR) - Page Router 處理 4 種渲染的方式 - 1. 客戶端渲染 (CSR) - 2. 伺服器端渲染 (SSR) - 3. 靜態網站生成 (SSG) - 4. 增量靜態再生 (ISR) - Page Router 處理 4 種渲染的方式總結 - App Router 處理 4 種渲染的方式 - 1. 客戶端渲染 (CSR) - 2. 伺服器端渲染 (SSR) - 3. 靜態網站生成 (SSG) - 4. 增量靜態再生 (ISR) - App Router 處理 4 種渲染的方式總結 - Rendering—— App Router 渲染概念 - 1. 伺服器元件（React Server Component, RSC） - 伺服器渲染的好處 - 在 Next.js 中使用伺服器元件 - 伺服器元件如何渲染？ - 伺服器渲染策略—— 1. 靜態渲染（預設） - 伺服器渲染策略—— 2. 動態渲染 - 伺服器渲染策略—— 3. 串流 - 2. 客戶端元件（Client Component） - 客戶端渲染的好處 - 在 Next.js 中使用客戶端元件 - 客戶端元件如何渲染？ - Routing——路由使用差異 - 1. 定義路由（Defining Routes） - 2. 佈局和模板（Layouts and Templates） - 3. 連結和導航（Linking and Navigating） - 4. 錯誤處理（Error Handling） - 5. 載入 UI 和串流（Loading UI and Streaming） - 6. 重新導向（Redirecting） - 7. 路由分組（Route Groups） - 8. 專案組織（Project Organization） - 9. 動態路由（Dynamic Routes） - 10. 平行路由（Parallel Routes） - 11. 攔截路由（Intercepting Routes） - 12. 路由處理程式（Route Handlers） - 13. 中介軟體（Middleware） - 14. 國際化（Internationalization） - Data Fetching——資料獲取差異 - 逐步遷移的方式 - 實作——App Router - 結論 - 條列式整理差異 - 適用情境 - 對於專案的建議 - 參考資料

[godmmt]

新增：「Routing——路由差異」之兩版本路由系統的路由詳細說明 (部分完成)

完成的部分：

• [x] 定義路由（Defining Routes）
• [x] 佈局和模板（Layouts and Templates）
• [ ] 連結和導航（Linking and Navigating）
• [ ] 錯誤處理（Error Handling）
• [ ] 載入 UI 和串流（Loading UI and Streaming）
• [ ] 重新導向（Redirecting）
• [ ] 路由分組（Route Groups）
• [ ] 專案組織（Project Organization）
• [ ] 動態路由（Dynamic Routes）
• [ ] 平行路由（Parallel Routes）
• [ ] 攔截路由（Intercepting Routes）
• [ ] 路由處理程式（Route Handlers）
• [ ] 中介軟體（Middleware）
• [ ] 國際化（Internationalization）

[godmmt]

took 3.5 hours

Total time: 8

done.

（今天因為 pre-commit 環境有問題，幾乎都在花時間排查錯誤、修復環境，所以處理 KM 的時間就不多了。）