next

用途

@json-render/next 是 json-render 的 Next.js 渲染器，作用是把 JSON 规格（spec）转换为完整的 Next.js 应用，涵盖路由、页面、布局、元数据以及 SSR 支持。

主要能力

NextAppSpec 顶层规格：定义整个 Next.js 应用，包含以下字段：

• metadata：根级 SEO 元数据（标题模板、描述、OpenGraph）
• layouts：可复用的布局元素树，每个布局必须包含一个 Slot 组件
• routes：以 URL 模式为键的路由定义
• state：跨所有路由共享的全局初始状态

路由模式：遵循 Next.js URL 约定，支持：

• "/" 首页
• "/about" 静态路由
• "/blog/[slug]" 动态段
• "/docs/[...path]" catch-all 段
• "/settings/[[...path]]" 可选 catch-all 段

布局：布局包裹页面内容，每个布局必须包含 Slot 组件以渲染页面内容。布局在 spec.layouts 中定义一次，路由通过 layout 字段引用。

内置组件：

• Slot：布局中渲染页面内容的占位符
• Link：客户端导航链接（封装 next/link）

内置动作：

• setState：更新状态值，参数 { statePath, value }
• pushState：向数组追加，参数 { statePath, value, clearStatePath? }
• removeState：按索引从数组移除，参数 { statePath, index }
• navigate：客户端导航，参数 { href }

数据加载器：服务端异步函数，在渲染前的 Server Component 中运行，结果合并到页面的初始状态。

SSR：页面自动服务端渲染。createNextApp 的 Page 组件是异步 Server Component，负责匹配路由、运行服务端数据加载器、生成元数据，并把解析后的 spec 传给客户端渲染器进行 hydration。

使用方式

安装：

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>
  );
}

数据加载器示例：

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

入口点

• @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 catalog 生成）
• matchRoute(spec, pathname)：将 URL 匹配到路由 spec
• resolveMetadata(spec, route)：解析路由的元数据
• slugToPath(slug)：将 catch-all slug 数组转换为 pathname
• collectStaticParams(spec)：收集所有路由的静态参数

客户端导出（@json-render/next）：

• NextAppProvider：registry 与 handlers 的上下文提供者
• PageRenderer：渲染页面 spec，可选布局
• NextErrorBoundary：错误边界组件
• NextLoading：加载状态组件
• NextNotFound：未找到组件
• Link：内置导航组件（封装 next/link）

适用场景

适合需要以 JSON 规格驱动、生成完整 Next.js 应用（含路由、布局、元数据与 SSR）的开发场景，尤其是希望统一管理页面结构、SEO 元数据与服务端数据加载的项目。

限制

资料未提供关于收费、价格、平台兼容性、性能效果等方面的信息，暂未提供。