AI Skills
next

next

熱門

Next.js 渲染器，用於 json-render，可將 JSON 規格轉換為完整的 Next.js 應用程式，包含路由、版面配置、SSR 與中繼資料。適用於搭配 @json-render/next 使用、從 JSON 規格建構 Next.js 應用程式，或建立 AI 生成的多頁面應用程式。

1.6萬星標
851分支
更新於 2026/7/8
獲取技能源代碼

相關技能

motion-advanced24萬next-partial-prefetching-adoption14萬migrate-radix-to-base12萬
SKILL.md
唯讀
名稱
next
描述

Next.js 渲染器，用於 json-render，可將 JSON 規格轉換為完整的 Next.js 應用程式，包含路由、版面配置、SSR 與中繼資料。適用於搭配 @json-render/next 使用、從 JSON 規格建構 Next.js 應用程式，或建立 AI 生成的多頁面應用程式。

@json-render/next

Next.js 渲染器，可將 JSON 規格轉換為完整的 Next.js 應用程式，包含路由、頁面、版面配置、中繼資料與 SSR 支援。

快速開始

npm install @json-render/core @json-render/react @json-render/next

1. 定義規格

// lib/spec.ts
import type { NextAppSpec } from "@json-render/next";

export const spec: NextAppSpec = {
  metadata: {
    title: { default: "My App", template: "%s | My App" },
    description: "一個 json-render Next.js 應用程式",
  },
  layouts: {
    main: {
      root: "shell",
      elements: {
        shell: { type: "Container", props: {}, children: ["nav", "slot"] },
        nav: { type: "NavBar", props: { links: [
          { href: "/", label: "首頁" },
          { href: "/about", label: "關於" },
        ]}, children: [] },
        slot: { type: "Slot", props: {}, children: [] },
      },
    },
  },
  routes: {
    "/": {
      layout: "main",
      metadata: { title: "首頁" },
      page: {
        root: "hero",
        elements: {
          hero: { type: "Card", props: { title: "歡迎" }, children: [] },
        },
      },
    },
    "/about": {
      layout: "main",
      metadata: { title: "關於" },
      page: {
        root: "content",
        elements: {
          content: { type: "Card", props: { title: "關於我們" }, children: [] },
        },
      },
    },
  },
};

2. 建立應用程式

// lib/app.ts
import { createNextApp } from "@json-render/next/server";
import { spec } from "./spec";

export const { Page, generateMetadata, generateStaticParams } = createNextApp({
  spec,
  loaders: {
    // 伺服器端資料載入器（選用）
    loadPost: async ({ slug }) => {
      const post = await getPost(slug as string);
      return { post };
    },
  },
});

3. 設定路由檔案

// app/[[...slug]]/page.tsx
export { Page as default, generateMetadata, generateStaticParams } from "@/lib/app";

// app/[[...slug]]/layout.tsx
import { NextAppProvider } from "@json-render/next";
import { registry, handlers } from "@/lib/registry";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh-TW">
      <body>
        <NextAppProvider registry={registry} handlers={handlers}>
          {children}
        </NextAppProvider>
      </body>
    </html>
  );
}

核心概念

NextAppSpec

頂層規格定義了整個 Next.js 應用程式：

  • metadata：根層級的 SEO 中繼資料（標題模板、描述、OpenGraph）
  • layouts：可重複使用的版面配置元素樹（每個必須包含一個 Slot 元件）
  • routes：以 URL 模式為鍵的路由定義
  • state：所有路由共用的全域初始狀態

路由模式

路由使用 Next.js URL 慣例：

  • "/" -- 首頁
  • "/about" -- 靜態路由
  • "/blog/[slug]" -- 動態區段
  • "/docs/[...path]" -- 捕獲所有區段
  • "/settings/[[...path]]" -- 可選的捕獲所有區段

版面配置

版面配置包覆頁面內容。每個版面配置必須包含一個 Slot 元件，頁面內容將在此處渲染。版面配置在 spec.layouts 中定義一次，並由路由透過 layout 欄位引用。

內建元件

  • Slot：版面配置中的佔位符，頁面內容在此渲染
  • Link：客戶端導航連結（包裝 next/link）

內建動作

  • setState：更新狀態值。參數：{ statePath, value }
  • pushState：附加到陣列。參數：{ statePath, value, clearStatePath? }
  • removeState：依索引從陣列移除。參數：{ statePath, index }
  • navigate：客戶端導航。參數：{ href }

資料載入器

在 Server Component 中於渲染前執行的伺服器端非同步函式。結果會合併到頁面的初始狀態中。

createNextApp({
  spec,
  loaders: {
    loadPost: async ({ slug }) => {
      const post = await db.post.findUnique({ where: { slug } });
      return { post };
    },
  },
});

SSR

頁面會自動進行伺服器端渲染。createNextApp 的 Page 元件是一個非同步 Server Component，它會：

  1. 從規格中比對路由
  2. 執行伺服器端資料載入器
  3. 產生中繼資料
  4. 將解析後的規格傳遞給客戶端渲染器進行水合

進入點

  • @json-render/next -- 客戶端元件（NextAppProvider、PageRenderer、Link）
  • @json-render/next/server -- 伺服器端工具（createNextApp、matchRoute、schema）

API 參考

伺服器端匯出（@json-render/next/server）

  • createNextApp(options) -- 建立 Page、generateMetadata、generateStaticParams
  • schema -- Next.js 應用程式的自訂 schema（用於 AI 目錄生成）
  • matchRoute(spec, pathname) -- 將 URL 比對到路由規格
  • resolveMetadata(spec, route) -- 解析路由的中繼資料
  • slugToPath(slug) -- 將捕獲所有 slug 陣列轉換為路徑名稱
  • collectStaticParams(spec) -- 收集所有路由的靜態參數

客戶端匯出（@json-render/next）

  • NextAppProvider -- 提供 registry 和 handlers 的 Context Provider
  • PageRenderer -- 渲染頁面規格（可選版面配置）
  • NextErrorBoundary -- 錯誤邊界元件
  • NextLoading -- 載入狀態元件
  • NextNotFound -- 找不到頁面元件
  • Link -- 內建導航元件（包裝 next/link）