json-render：Vercel 开源的 Generative UI 框架

本文介绍 json-render，一个由 Vercel Labs 开源的 Generative UI 框架。它允许开发者通过自然语言提示生成动态、个性化的用户界面，同时保持可靠性和可预测性。

项目简介

json-render 是一个生成式 UI 框架，AI 可以根据自然语言提示生成界面，但仅限于你定义的组件范围内。这种设计让开发者既能享受 AI 生成界面的便利，又能保持对输出结果的完全控制。

截至目前，该项目在 GitHub 上已获得 11.1k stars 和 586 forks，主要由 TypeScript (82.4%) 编写，采用 Apache-2.0 开源协议。

核心特性

Guardrailed（受控的）：AI 只能使用组件目录中预定义的组件
Predictable（可预测的）：JSON 输出始终符合你的 Schema，每次结果一致
Fast（快速的）：支持流式渲染，模型响应时即可渐进式渲染
Cross-Platform（跨平台的）：一套组件目录可同时生成 React (Web) 和 React Native (移动端) 代码
Batteries Included（开箱即用）：内置 36 个预置的 shadcn/ui 组件，可直接使用

技术栈

TypeScript - 核心开发语言（82.4%）
React / React Native - UI 渲染目标
Zod - Schema 验证和类型定义
Radix UI + Tailwind CSS - shadcn/ui 组件基础
Remotion - 视频渲染支持
React PDF - PDF 文档生成

安装指南

基础安装（React）

bash

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

使用 shadcn/ui 组件

bash

npm install @json-render/shadcn

移动端（React Native）

bash

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

视频渲染（Remotion）

bash

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

PDF 文档

bash

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

快速开始

1. 定义组件目录

typescript

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react";
import { z } from "zod";

const catalog = defineCatalog(schema, {
  components: {
    Card: {
      props: z.object({ title: z.string() }),
      description: "A card container",
    },
    Metric: {
      props: z.object({
        label: z.string(),
        value: z.string(),
        format: z.enum(["currency", "percent", "number"]).nullable(),
      }),
      description: "Display a metric value",
    },
    Button: {
      props: z.object({
        label: z.string(),
        action: z.string(),
      }),
      description: "Clickable button",
    },
  },
  actions: {
    export_report: {
      description: "Export dashboard to PDF"
    },
    refresh_data: {
      description: "Refresh all metrics"
    },
  },
});

2. 定义组件实现

typescript

import { defineRegistry, Renderer } from "@json-render/react";

const { registry } = defineRegistry(catalog, {
  components: {
    Card: ({ props, children }) => (
      <div className="card">
        <h3>{props.title}</h3>
        {children}
      </div>
    ),
    Metric: ({ props }) => (
      <div className="metric">
        <span>{props.label}</span>
        <span>{format(props.value, props.format)}</span>
      </div>
    ),
    Button: ({ props, emit }) => (
      <button onClick={() => emit("press")}>
        {props.label}
      </button>
    ),
  },
});

3. 渲染 AI 生成的 Spec

typescript

function Dashboard({ spec }) {
  return <Renderer spec={spec} registry={registry} />;
}

核心概念：AI 生成 JSON，你安全地渲染它。

使用示例

React UI 渲染

typescript

import { defineRegistry, Renderer } from "@json-render/react";
import { schema } from "@json-render/react";

// Flat spec format (root key + elements map)
const spec = {
  root: "card-1",
  elements: {
    "card-1": {
      type: "Card",
      props: { title: "Hello" },
      children: ["button-1"],
    },
    "button-1": {
      type: "Button",
      props: { label: "Click me" },
      children: [],
    },
  },
};

<Renderer spec={spec} registry={registry} />

使用 shadcn/ui 组件

typescript

import { defineCatalog } from "@json-render/core";
import { schema, defineRegistry, Renderer } from "@json-render/react";
import { shadcnComponentDefinitions } from "@json-render/shadcn/catalog";
import { shadcnComponents } from "@json-render/shadcn";

const catalog = defineCatalog(schema, {
  components: {
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,
    Heading: shadcnComponentDefinitions.Heading,
    Button: shadcnComponentDefinitions.Button,
  },
  actions: {},
});

const { registry } = defineRegistry(catalog, {
  components: {
    Card: shadcnComponents.Card,
    Stack: shadcnComponents.Stack,
    Heading: shadcnComponents.Heading,
    Button: shadcnComponents.Button,
  },
});

React Native 移动端

typescript

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react-native/schema";
import {
  standardComponentDefinitions,
  standardActionDefinitions,
} from "@json-render/react-native/catalog";
import { defineRegistry, Renderer } from "@json-render/react-native";

const catalog = defineCatalog(schema, {
  components: { ...standardComponentDefinitions },
  actions: standardActionDefinitions,
});

const { registry } = defineRegistry(catalog, { components: {} });
<Renderer spec={spec} registry={registry} />

Remotion 视频渲染

typescript

import { Player } from "@remotion/player";
import { Renderer, schema, standardComponentDefinitions } from "@json-render/remotion";

const spec = {
  composition: {
    id: "video",
    fps: 30,
    width: 1920,
    height: 1080,
    durationInFrames: 300
  },
  tracks: [{ id: "main", name: "Main", type: "video", enabled: true }],
  clips: [{
    id: "clip-1",
    trackId: "main",
    component: "TitleCard",
    props: { title: "Hello" },
    from: 0,
    durationInFrames: 90
  }],
  audio: { tracks: [] }
};

<Player
  component={Renderer}
  inputProps={{ spec }}
  durationInFrames={spec.composition.durationInFrames}
  fps={spec.composition.fps}
  compositionWidth={spec.composition.width}
  compositionHeight={spec.composition.height}
/>

高级功能

流式渲染（SpecStream）

支持渐进式流式渲染 AI 响应：

typescript

import { createSpecStreamCompiler } from "@json-render/core";

const compiler = createSpecStreamCompiler<MySpec>();

// 处理到达的数据块
const { result, newPatches } = compiler.push(chunk);
setSpec(result); // 用部分结果更新 UI

// 获取最终结果
const finalSpec = compiler.getResult();

AI 提示生成

从组件目录自动生成系统提示：

typescript

const systemPrompt = catalog.prompt();
// 包含组件描述、属性 Schema、可用动作

条件可见性

组件可根据状态条件显示/隐藏：

json

{
  "type": "Alert",
  "props": { "message": "Error occurred" },
  "visible": [
    { "$state": "/form/hasError" },
    { "$state": "/form/errorDismissed", "not": true }
  ]
}

动态属性

任何属性值都可以使用表达式动态计算：

json

{
  "type": "Icon",
  "props": {
    "name": {
      "$cond": { "$state": "/activeTab", "eq": "home" },
      "$then": "home",
      "$else": "home-outline"
    }
  }
}

本地演示

bash

git clone https://github.com/vercel-labs/json-render
cd json-render
pnpm install
pnpm dev

启动后访问：

http://localhost:3000 - 文档和 Playground
http://localhost:3001 - Dashboard 示例
http://localhost:3002 - Remotion 视频示例

工作原理

json-render 的工作流程：

定义约束 - 确定 AI 可以使用的组件、动作和数据绑定
提示 - 用自然语言描述你想要的界面
AI 生成 JSON - 输出始终可预测，受限于你的组件目录
快速渲染 - 模型响应时即可流式渐进渲染

包说明

包名	说明
@json-render/core	Schema、目录、AI 提示、动态属性、SpecStream 工具
@json-render/react	React 渲染器、上下文、Hooks
@json-render/shadcn	36 个预置 shadcn/ui 组件（Radix UI + Tailwind CSS）
@json-render/react-native	React Native 渲染器，包含标准移动端组件
@json-render/remotion	Remotion 视频渲染器，时间线 Schema
@json-render/react-pdf	React PDF 渲染器，用于从 Spec 生成 PDF 文档

项目链接

GitHub 仓库: https://github.com/vercel-labs/json-render
官方文档: https://json-render.dev
协议: Apache-2.0

字节笔记本

json-render：Vercel 开源的 Generative UI 框架

项目简介

核心特性

技术栈

安装指南

基础安装（React）

使用 shadcn/ui 组件

移动端（React Native）

视频渲染（Remotion）

PDF 文档

快速开始

1. 定义组件目录

2. 定义组件实现

3. 渲染 AI 生成的 Spec

使用示例

React UI 渲染

使用 shadcn/ui 组件

React Native 移动端

Remotion 视频渲染

高级功能

流式渲染（SpecStream）

AI 提示生成

条件可见性

动态属性

本地演示

工作原理

包说明

项目链接