next

@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: "A json-render Next.js application",
  },
  layouts: {
    main: {
      root: "shell",
      elements: {
        shell: { type: "Container", props: {}, children: ["nav", "slot"] },
        nav: { type: "NavBar", props: { links: [
          { href: "/", label: "Home" },
          { href: "/about", label: "About" },
        ]}, children: [] },
        slot: { type: "Slot", props: {}, children: [] },
      },
    },
  },
  routes: {
    "/": {
      layout: "main",
      metadata: { title: "Home" },
      page: {
        root: "hero",
        elements: {
          hero: { type: "Card", props: { title: "Welcome" }, children: [] },
        },
      },
    },
    "/about": {
      layout: "main",
      metadata: { title: "About" },
      page: {
        root: "content",
        elements: {
          content: { type: "Card", props: { title: "About Us" }, children: [] },
        },
      },
    },
  },
};

2. 创建应用

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

export const { Page, generateMetadata, generateStaticParams } = createNextApp({
  spec,
  loaders: {
    // Server-side data loaders (optional)
    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="en">
      <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）