Communitygithub.com

ASoudy/AGS

Next.js App Router 開發原則:伺服器元件、資料擷取與路由模式。

AGS 是什麼?

此技能提供 Next.js App Router 開發的完整最佳實踐指南,涵蓋伺服器元件與客戶端元件的選擇決策樹、資料擷取策略 (靜態、ISR、動態)、路由組織慣例 (頁面、佈局、載入狀態、錯誤邊界)、API 路由處理、效能最佳化 (圖片、Bundle)、中繼資料管理及快取策略。支援 Next.js 13+ 的 App Router 模式,強調「以伺服器元件為預設」的原則,僅在必要時使用客戶端元件。工作流程包括根據互動需求決定元件類型、選擇適當的快取與資料擷取模式,以及利用 Route Groups、Parallel Routes 等進階路由功能組織專案結構。此技能特別適合需要開發高效能、SEO 友善且具良好使用者體驗的 Next.js 應用的開發者。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/AGAS/plugins/antigravity-awesome-skills-claude/skills/nextjs-best-practices

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Next.js 最佳實踐

Next.js App Router 開發原則。


1. 伺服器元件 vs 用戶端元件

決策樹

需要...?
│
├── useState, useEffect, 事件處理器
│   └── 用戶端元件 ('use client')
│
├── 直接資料擷取,無需互動
│   └── 伺服器元件 (預設)
│
└── 兩者都需要?
    └── 拆分:伺服器父元件 + 用戶端子元件

預設使用

類型用途
伺服器資料擷取、佈局、靜態內容
用戶端表單、按鈕、互動式 UI

2. 資料擷取模式

擷取策略

模式用途
預設靜態 (建置時快取)
重新驗證ISR (基於時間的重新整理)
無儲存動態 (每次請求)

資料流

來源模式
資料庫伺服器元件擷取
API使用快取的擷取
使用者輸入用戶端狀態 + 伺服器動作

3. 路由原則

檔案慣例

檔案用途
page.tsx路由 UI
layout.tsx共用佈局
loading.tsx載入狀態
error.tsx錯誤邊界
not-found.tsx404 頁面

路由組織

模式用途
路由群組 (name)不影響 URL 的組織方式
平行路由 @slot同一層級的多個頁面
攔截路由 (.)模態視窗覆蓋

4. API 路由

路由處理器

方法用途
GET讀取資料
POST建立資料
PUT/PATCH更新資料
DELETE刪除資料

最佳實踐

  • 使用 Zod 驗證輸入
  • 回傳正確的狀態碼
  • 優雅地處理錯誤
  • 盡可能使用 Edge runtime

5. 效能原則

圖片最佳化

  • 使用 next/image 元件
  • 為首屏圖片設定 priority
  • 提供模糊佔位圖
  • 使用響應式尺寸

Bundle 最佳化

  • 對重量級元件使用動態匯入
  • 基於路由的程式碼分割 (自動)
  • 使用 Bundle Analyzer 分析

6. 中繼資料

靜態 vs 動態

類型用途
靜態匯出固定中繼資料
generateMetadata每個路由的動態中繼資料

必要標籤

  • title (50-60 字元)
  • description (150-160 字元)
  • Open Graph 圖片
  • 標準網址

7. 快取策略

快取層級

層級控制方式
請求fetch 選項
資料revalidate/tags
完整路由路由設定

重新驗證

方法用途
基於時間revalidate: 60
隨需revalidatePath/Tag
無快取no-store

8. 伺服器動作

使用場景

  • 表單提交
  • 資料變更
  • 重新驗證觸發

最佳實踐

  • 標記為 'use server'
  • 驗證所有輸入
  • 回傳型別化的回應
  • 處理錯誤

9. 反模式

❌ 不要✅ 應該
到處都用 'use client'預設使用伺服器元件
在用戶端元件中擷取資料在伺服器元件中擷取
跳過載入狀態使用 loading.tsx
忽略錯誤邊界使用 error.tsx
大型客戶端 Bundle動態匯入

10. 專案結構

app/
├── (marketing)/     # 路由群組
│   └── page.tsx
├── (dashboard)/
│   ├── layout.tsx   # 儀表板佈局
│   └── page.tsx
├── api/
│   └── [resource]/
│       └── route.ts
└── components/
    └── ui/

切記: 伺服器元件是預設選項,有其充分的理由。從那裡開始,只在需要時才加入用戶端元件。

使用時機

此技能適用於執行概述中所述的工作流程或操作。

限制

  • 僅在任務與上述範圍明確相符時使用此技能。
  • 請勿將輸出視為環境特定驗證、測試或專家審查的替代品。
  • 若缺少必要的輸入、權限、安全邊界或成功標準,請停止並要求澄清。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

相關技能