json-render：用受控JSON让AI生成跨框架界面
给前端团队用的AI界面框架，让模型按catalog生成可控JSON，而非自由写UI。
GitHub vercel-labs/json-render 更新 2026-09-21 分支 main 星标 17.3K 分叉 919
TypeScript Generative UI JSON Schema React/Vue/Svelte/Solid React Native

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你在React中需要让AI生成受限于Card、Metric和Button的Dashboard。
    README“Quick Start”展示了defineCatalog、defineRegistry和Renderer的完整流程。
  • 你要让React、Vue、Svelte或Solid共享一套UI catalog。
    README“Why json-render?”明确列出React、Vue、Svelte、Solid的Cross-Platform能力。
  • 你需要在模型响应时逐步显示界面，而不是等待完整JSON。
    README“Why json-render?”列出“Stream and render progressively”，Packages中有SpecStream utilities。
  • 你需要从同一份spec生成Next.js应用、PDF、HTML邮件或Remotion视频。
    README“Packages”列出@json-render/next、@json-render/react-pdf、@json-render/react-email和@json-render/remotion。

不适合，如果你

  • 你要求使用Jev composition作为已发布的稳定生产能力。
    README“Demo”将Jev composition标记为“Experimental”和“Unreleased”。
  • 你的目标框架不在README列出的React、Vue、Svelte、Solid、React Native等渲染器中。
    README“Packages”只列出了具体的框架适配器，未列出其他目标框架。
  • 你需要README明确保证的模型供应商、认证方案或生产安全边界。
    提供的README材料没有说明模型供应商、认证方案或生产安全边界。

前置条件

  • React项目可安装：npm install @json-render/core @json-render/react
  • 使用预构建shadcn/ui组件时安装：npm install @json-render/shadcn
  • 从源码运行Demo需要执行git clone、cd json-render、pnpm install和pnpm dev
  • React Native示例需要运行npx expo start
  • README示例使用TypeScript、React、Zod和@json-render/react/schema

第一步命令（README 原文）

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

要注意

  • 不要把Jev composition当作稳定API使用，因为README标注其未发布。
    README“Demo”写明“Experimental Jev composition”且“Unreleased”。
  • 选择Svelte时要对应Svelte 5 renderer和runes-based reactivity。
    README“Packages”将@json-render/svelte描述为“Svelte 5 renderer with runes-based reactivity”。
  • 选择3D能力时需额外安装@react-three/fiber、@react-three/drei和three。
    README安装命令中的React Three Fiber方案列出了这些依赖。
  • Dashboard动作需要在catalog中显式声明，例如export_report和refresh_data。
    README“Define Your Catalog”示例在actions中声明了export_report和refresh_data。

材料未说明

  • README未说明支持哪些AI模型供应商及对应SDK版本。
  • README未说明Node.js、浏览器或React的最低版本要求。
  • README未提供JSON生成失败、schema校验失败或模型超时的处理策略。
  • README未给出SpecStream在不同模型和界面规模下的性能数据。
  • README未说明catalog actions的权限控制、认证和副作用隔离方式。
  • README未说明10位贡献者和5个版本对应的发布维护承诺。

💡 深度解析

6
适合 我维护一个 React 产品，希望直接使用项目提供的 36 个 shadcn/ui 组件，让 AI 生成受控的仪表盘；这个方案能否避免模型生成不存在的组件和错误属性？
适合读者： 维护 React 产品、希望使用 36 个预构建 shadcn/ui 组件快速加入 AI 仪表盘的前端工程师

适合，因为 React 渲染器、组件目录和 Schema 约束正好覆盖这个需求，但它不会替你保证仪表盘的业务语义正确。

  • AI 只能使用开发者放入 catalog 的组件，不能直接生成任意组件或前端代码。
  • Props 可通过 Schema 约束，README 将输出描述为“JSON output matches your schema”。
  • @json-render/shadcn 已提供 36 个基于 Radix UI 与 Tailwind CSS 的组件，可减少基础组件注册工作。
  • 仍需自己定义 catalog、组件注册和动作；未注册的业务组件不会自动出现。
  • Why json-render?: “AI can only use components in your catalog”
  • Why json-render?: “JSON output matches your schema, every time”
  • Packages: `@json-render/shadcn` — 36 pre-built shadcn/ui components
  • How It Works: “Define the guardrails - what components, actions, and data bindings AI can use”
npm install @json-render/shadcn
材料未说明：README 未说明 36 个组件具体覆盖哪些业务控件，以及每个组件的默认 Props Schema。；README 未说明不同模型、提示词和复杂布局下的生成准确率。
适合 我已经使用 Next.js，并希望 AI 不只生成组件树，还能生成包含 routes、layouts、SSR 和 metadata 的完整应用；json-render 能否覆盖这个层级？
适合读者： 使用 Next.js、需要让 AI 生成包含路由、布局、SSR 和元数据的完整应用页面的全栈工程师

适合，README 明确把 Next.js 支持定位为完整应用渲染，而不只是单个 React 组件；但具体路由权限和业务服务仍不由 JSON Spec 自动解决。

  • @json-render/next 的描述直接包含 routes、layouts 和 SSR。
  • 安装示例明确称其为 “full Next.js apps (routes, layouts, SSR, metadata)”。
  • JSON Spec 仍需通过 catalog 和 renderer 映射到真实实现，模型不能绕过已定义的能力边界。
  • 项目核心语言是 TypeScript，Next.js 相关集成与其技术栈一致；但 README 未承诺完整的鉴权、数据加载或部署方案。
  • Packages: `@json-render/next` — “Next.js renderer — JSON becomes full apps with routes, layouts, SSR”
  • 安装示例：`npm install @json-render/core @json-render/react @json-render/next`
  • 安装示例：`full Next.js apps (routes, layouts, SSR, metadata)`
  • 项目核心数据：main_language 为 TypeScript
npm install @json-render/core @json-render/react @json-render/next
材料未说明：README 未说明生成式路由的鉴权、数据加载、缓存和错误边界集成方式。；README 未说明 SSR 输出对流式 Spec、不完整 Spec 和 SEO 的具体处理。
视情况 我需要把 AI 生成的内容分别输出为 HTML 邮件、PDF 文档和 Remotion 视频，希望尽量复用同一套 JSON UI Spec；这个项目是否适合这种多媒介输出？
适合读者： 需要从同一类结构化描述生成 React Email、PDF 文档和 Remotion 视频的内容应用开发者

视情况：项目确实提供三类对应 renderer 和统一 JSON Spec，但邮件、PDF 与视频的排版能力并不等价，不能把 Web 组件无修改地当作所有输出媒介的通用组件。

  • Packages 列出 @json-render/react-email、@json-render/react-pdf 和 @json-render/remotion。
  • README 的安装示例分别覆盖 HTML/plain-text email、PDF documents 和 video。
  • 核心 JSON Spec 与 catalog 可以复用结构化意图，具体组件和布局仍由目标 renderer 实现。
  • Remotion 还使用 timeline schema，说明视频输出存在不同于文档和邮件的专用模型。
  • Packages: `@json-render/remotion` — Remotion video renderer, timeline schema
  • Packages: `@json-render/react-pdf` — React PDF renderer for generating PDF documents from specs
  • Packages: `@json-render/react-email` — React Email renderer for HTML/plain-text emails from specs
  • 安装示例：`npm install @json-render/core @json-render/remotion`、`@json-render/react-pdf`、`@json-render/react-email ...`
npm install @json-render/core @json-render/react-pdf
材料未说明：README 未说明不同 renderer 之间哪些组件和布局字段可以直接复用。；README 未说明 PDF 分页、邮件客户端兼容性和 Remotion 时间轴表达的具体限制。
视情况 我需要同时维护 React、Vue、Svelte 和 SolidJS 四个 Web 渲染环境，希望 AI 只生成一套 JSON UI Spec；这个项目能否减少四套界面逻辑的重复？
适合读者： 需要让同一套界面描述运行在 React、Vue、Svelte 和 SolidJS 的跨端前端工程师

视情况：项目明确支持多种 Web renderer 和同一 catalog，但共享的是 JSON 描述与设计意图，不是四个平台的实现细节完全相同。

  • README 将 React、Vue、Svelte、Solid 列为同一 catalog 可覆盖的跨平台 Web 环境。
  • @json-render/core 提供 schemas、catalogs、AI prompts 和 SpecStream，renderer 包负责具体平台输出。
  • 每个平台仍需要安装对应 renderer，并为真实组件建立映射；平台特有的交互和布局不能自动抹平。
  • shadcn/ui 与 shadcn-svelte 分别提供 36 个组件，说明组件实现仍按平台区分。
  • Why json-render?: “Cross-Platform - React, Vue, Svelte, Solid (web), React Native (mobile) from the same catalog”
  • Packages: `@json-render/core` — schemas, catalogs, AI prompts, dynamic props, SpecStream utilities
  • Packages: `@json-render/vue`, `@json-render/svelte`, `@json-render/solid`
  • Packages: `@json-render/shadcn` and `@json-render/shadcn-svelte`
npm install @json-render/core @json-render/react
材料未说明：README 未说明同一 catalog 在四个 renderer 之间的组件兼容子集。；README 未说明平台差异组件如何回退、忽略或在 JSON Spec 中表达。
适合 我正在用 React Native 做移动端产品，希望 AI 生成表单和信息展示界面，但只能使用标准移动组件；json-render 是否适合，而不是继续让模型输出任意 React 代码？
适合读者： 使用 React Native 构建移动端产品、希望让自然语言生成受控移动界面的移动端工程师

适合，前提是你的移动界面可以表达为目录中的受控组件和动作，而不是依赖任意 React Native 代码。

  • README 提供独立的 @json-render/react-native renderer，并明确将 React Native 归为 mobile 目标。
  • AI 输出的是受 catalog 限制的 JSON，而不是可执行的任意 JavaScript 或 React Native 源码。
  • 核心包支持 dynamic props、actions 和 SpecStream，可覆盖动态表单或状态驱动界面的基础模型。
  • 移动端仍需单独实现或选择组件注册；Web 组件不能假设可直接复用到 React Native。
  • 安装示例：`npm install @json-render/core @json-render/react-native`
  • Why json-render?: “Cross-Platform - React, Vue, Svelte, Solid (web), React Native (mobile) from the same catalog”
  • Packages: `@json-render/core` — dynamic props, SpecStream utilities
  • How It Works: “AI generates JSON” and “what components, actions, and data bindings AI can use”
npm install @json-render/core @json-render/react-native
材料未说明：README 未列出 React Native renderer 内置的具体组件清单。；README 未说明 iOS 与 Android 的平台差异、原生模块和导航集成方式。
适合 我正在构建面向 Claude、ChatGPT、Cursor 或 VS Code 的 MCP App，希望 AI 生成可交互界面，但只能调用我预先定义的组件和动作；json-render 是否适合作为受控 UI 层？
适合读者： 构建 Claude、ChatGPT、Cursor 或 VS Code 的 MCP Apps，并希望 AI 输出只能触发预定义动作的 Agent 开发者

适合，项目同时提供 MCP Apps 集成和 catalog/action 约束，能够把 Agent 的界面输出限制在预定义能力内；但动作本身仍需要应用侧的权限与参数校验。

  • @json-render/mcp 明确支持 Claude、ChatGPT、Cursor 和 VS Code 的 MCP Apps integration。
  • How It Works 要求开发者定义 AI 可使用的 components、actions 和 data bindings。
  • AI 生成 JSON Spec，renderer 再将其映射到真实组件，因此不是直接执行任意模型代码。
  • README 只说明集成与 UI 约束，没有说明 MCP 工具授权、用户身份、审计或动作失败恢复机制。
  • Packages: `@json-render/mcp` — MCP Apps integration for Claude, ChatGPT, Cursor, VS Code
  • How It Works: “Define the guardrails - what components, actions, and data bindings AI can use”
  • Why json-render?: “Predefined components and actions for safe, predictable output”
  • 项目洞察：核心采用 “Catalog + JSON UI Spec + Renderer” 架构
材料未说明：README 未提供 `@json-render/mcp` 的安装命令或最小集成示例。；README 未说明 MCP 工具调用与 json-render actions 之间的映射、授权和审计接口。；项目数据仅显示最新版本为 v0.21.0、共发布 5 个版本，README 未说明 MCP 集成的稳定性承诺。

✨ 核心亮点

  • catalog限制AI只能调用预定义组件与actions
  • SpecStream支持模型响应过程中的渐进渲染
  • 同一catalog覆盖React、Vue、Svelte和Solid
  • 提供36个预构建shadcn/ui组件
  • 支持Next.js完整应用与React Native移动端
  • 社区有17,311颗星和919个fork

🔧 工程化

  • 用defineCatalog声明Card、Metric、Button及export_report动作
  • 用React的Renderer把AI生成的JSON spec安全渲染
  • 同一套组件目录可输出PDF、邮件、视频和3D场景
  • 提供MCP Apps集成，覆盖Claude、ChatGPT、Cursor和VS Code

⚠️ 风险

  • Jev composition标为Experimental且未发布，不宜当稳定能力
  • 项目仅有10位贡献者和5个版本，生态成熟度有限
  • README未说明模型供应商、认证和生产安全边界
  • JSON约束依赖自定义catalog，未展示异常输出处理细节

👥 适合谁？

  • 使用React并需要AI生成受控Dashboard的前端团队
  • 需要跨React、Vue、Svelte和Solid复用组件目录的团队
  • 构建Next.js路由、SSR和metadata动态应用的开发者
  • 需要React Native、Remotion或React PDF输出的团队