AI Skills
next

next

热门

json-render 的 Next.js 渲染器，将 JSON 规范转换为完整的 Next.js 应用程序，支持路由、布局、SSR 和元数据。当使用 @json-render/next、从 JSON 规范构建 Next.js 应用或创建 AI 生成的多页面应用时使用。

1.6万Star
851Fork
更新于 2026/7/8
获取 Skill源代码

相关 Skills

frontend-code-review15万migrate-radix-to-base12万shadcn12万
SKILL.md
readonly只读
name
next
description

json-render 的 Next.js 渲染器，将 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-CN">
      <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 -- 注册表和处理器上下文提供者
  • PageRenderer -- 渲染页面规范，可选布局
  • NextErrorBoundary -- 错误边界组件
  • NextLoading -- 加载状态组件
  • NextNotFound -- 未找到组件
  • Link -- 内置导航组件（包装 next/link）