json-render README

The project's README from github.com/vercel-labs/json-render. As one markdown file: README.md.

json-render

The Generative UI framework.

Generate dynamic, personalized UIs from prompts without sacrificing reliability. Predefined components and actions for safe, predictable output.

# for React
npm install @json-render/core @json-render/react
# for React with pre-built shadcn/ui components
npm install @json-render/shadcn
# or for React Native
npm install @json-render/core @json-render/react-native
# or for video
npm install @json-render/core @json-render/remotion
# or for PDF documents
npm install @json-render/core @json-render/react-pdf
# or for HTML email
npm install @json-render/core @json-render/react-email @react-email/components @react-email/render
# or for Vue
npm install @json-render/core @json-render/vue
# or for Svelte
npm install @json-render/core @json-render/svelte
# or for SolidJS
npm install @json-render/core @json-render/solid
# or for terminal UIs
npm install @json-render/core @json-render/ink ink react
# or for full Next.js apps (routes, layouts, SSR, metadata)
npm install @json-render/core @json-render/react @json-render/next
# or for 3D scenes (and gaussian splatting via the GaussianSplat component)
npm install @json-render/core @json-render/react-three-fiber @react-three/fiber @react-three/drei three

Why json-render?

json-render is a Generative UI framework: AI generates interfaces from natural language prompts, constrained to components you define. You set the guardrails, AI generates within them:

Quick Start

1. Define Your Catalog

import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";
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. Define Your Components

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. Render AI-Generated Specs

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

That's it. AI generates JSON, you render it safely.

Packages

Package Description
@json-render/core Schemas, catalogs, AI prompts, dynamic props, SpecStream utilities
@json-render/react React renderer, contexts, hooks
@json-render/vue Vue 3 renderer, composables, providers
@json-render/svelte Svelte 5 renderer with runes-based reactivity
@json-render/solid SolidJS renderer with fine-grained reactive contexts
@json-render/shadcn 36 pre-built shadcn/ui components (Radix UI + Tailwind CSS)
@json-render/shadcn-svelte 36 pre-built shadcn-svelte components (Svelte 5 + Tailwind CSS)
@json-render/react-three-fiber React Three Fiber renderer for 3D scenes (20 built-in components, including GaussianSplat)
@json-render/react-native React Native renderer with standard mobile components
@json-render/next Next.js renderer — JSON becomes full apps with routes, layouts, SSR
@json-render/tanstack-start TanStack Start renderer — full apps with routes, layouts, SSR, and head metadata
@json-render/remotion Remotion video renderer, timeline schema
@json-render/react-pdf React PDF renderer for generating PDF documents from specs
@json-render/react-email React Email renderer for HTML/plain-text emails from specs
@json-render/ink Ink terminal renderer with built-in components for interactive TUIs.
@json-render/image Image renderer for SVG/PNG output (OG images, social cards) via Satori
@json-render/directives Pre-built custom directives — $format, $math, $concat, $count, $truncate, $pluralize, $join, $t (i18n)
@json-render/codegen Utilities for generating code from json-render UI trees
@json-render/devtools Framework-agnostic devtools core — panel UI, event store, picker, stream taps
@json-render/devtools-react React adapter for @json-render/devtools (drop-in <JsonRenderDevtools />)
@json-render/devtools-vue Vue adapter for @json-render/devtools
@json-render/devtools-svelte Svelte adapter for @json-render/devtools
@json-render/devtools-solid SolidJS adapter for @json-render/devtools
@json-render/redux Redux / Redux Toolkit adapter for StateStore
@json-render/zustand Zustand adapter for StateStore
@json-render/jotai Jotai adapter for StateStore
@json-render/xstate XState Store (atom) adapter for StateStore
@json-render/mcp MCP Apps integration for Claude, ChatGPT, Cursor, VS Code
@json-render/yaml YAML wire format with streaming parser, edit modes, AI SDK transform

Renderers

React (UI)

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

// 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: [],
    },
  },
};

// defineRegistry creates a type-safe component registry
const { registry } = defineRegistry(catalog, { components });
<Renderer spec={spec} registry={registry} />;

Vue (UI)

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

const { registry } = defineRegistry(catalog, {
  components: {
    Card: ({ props, children }) =>
      h("div", { class: "card" }, [h("h3", null, props.title), children]),
    Button: ({ props, emit }) =>
      h("button", { onClick: () => emit("press") }, props.label),
  },
});

// In your Vue component template:
// <Renderer :spec="spec" :registry="registry" />

Svelte (UI)

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

const { registry } = defineRegistry(catalog, {
  components: {
    Card: ({ props, children }) => /* Svelte 5 snippet */,
    Button: ({ props, emit }) => /* Svelte 5 snippet */,
  },
});

// In your Svelte component:
// <Renderer spec={spec} registry={registry} />

Solid (UI)

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

const { registry } = defineRegistry(catalog, {
  components: {
    Card: (renderProps) => <div>{renderProps.children}</div>,
    Button: (renderProps) => (
      <button onClick={() => renderProps.emit("press")}>
        {renderProps.element.props.label as string}
      </button>
    ),
  },
});

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

shadcn/ui (Web)

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

// Pick components from the 36 standard definitions
const catalog = defineCatalog(schema, {
  components: {
    Card: shadcnComponentDefinitions.Card,
    Stack: shadcnComponentDefinitions.Stack,
    Heading: shadcnComponentDefinitions.Heading,
    Button: shadcnComponentDefinitions.Button,
  },
  actions: {},
});

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

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

React Native (Mobile)

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";

// 25+ standard components included
const catalog = defineCatalog(schema, {
  components: { ...standardComponentDefinitions },
  actions: standardActionDefinitions,
});

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

Remotion (Video)

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

// Timeline spec format
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}
/>;

React PDF (Documents)

import { renderToBuffer } from "@json-render/react-pdf";

const spec = {
  root: "doc",
  elements: {
    doc: {
      type: "Document",
      props: { title: "Invoice" },
      children: ["page-1"],
    },
    "page-1": {
      type: "Page",
      props: { size: "A4" },
      children: ["heading-1", "table-1"],
    },
    "heading-1": {
      type: "Heading",
      props: { text: "Invoice #1234", level: "h1" },
      children: [],
    },
    "table-1": {
      type: "Table",
      props: {
        columns: [
          { header: "Item", width: "60%" },
          { header: "Price", width: "40%", align: "right" },
        ],
        rows: [
          ["Widget A", "$10.00"],
          ["Widget B", "$25.00"],
        ],
      },
      children: [],
    },
  },
};

// Render to buffer, stream, or file
const buffer = await renderToBuffer(spec);

React Email (Email)

import { renderToHtml } from "@json-render/react-email";
import { schema, standardComponentDefinitions } from "@json-render/react-email";
import { defineCatalog } from "@json-render/core";

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

const spec = {
  root: "html-1",
  elements: {
    "html-1": {
      type: "Html",
      props: { lang: "en", dir: "ltr" },
      children: ["head-1", "body-1"],
    },
    "head-1": { type: "Head", props: {}, children: [] },
    "body-1": {
      type: "Body",
      props: { style: { backgroundColor: "#f6f9fc" } },
      children: ["container-1"],
    },
    "container-1": {
      type: "Container",
      props: {
        style: { maxWidth: "600px", margin: "0 auto", padding: "20px" },
      },
      children: ["heading-1", "text-1"],
    },
    "heading-1": { type: "Heading", props: { text: "Welcome" }, children: [] },
    "text-1": {
      type: "Text",
      props: { text: "Thanks for signing up." },
      children: [],
    },
  },
};

const html = await renderToHtml(spec);

Image (SVG/PNG)

import { renderToPng } from "@json-render/image/render";

const spec = {
  root: "frame",
  elements: {
    frame: {
      type: "Frame",
      props: { width: 1200, height: 630, backgroundColor: "#1a1a2e" },
      children: ["heading"],
    },
    heading: {
      type: "Heading",
      props: { text: "Hello World", level: "h1", color: "#ffffff" },
      children: [],
    },
  },
};

// Render to PNG (requires @resvg/resvg-js)
const png = await renderToPng(spec, { fonts });

// Or render to SVG string
import { renderToSvg } from "@json-render/image/render";
const svg = await renderToSvg(spec, { fonts });

Three.js (3D)

import { defineCatalog } from "@json-render/core";
import { schema, defineRegistry } from "@json-render/react";
import {
  threeComponentDefinitions,
  threeComponents,
  ThreeCanvas,
} from "@json-render/react-three-fiber";

const catalog = defineCatalog(schema, {
  components: {
    Box: threeComponentDefinitions.Box,
    Sphere: threeComponentDefinitions.Sphere,
    AmbientLight: threeComponentDefinitions.AmbientLight,
    DirectionalLight: threeComponentDefinitions.DirectionalLight,
    GaussianSplat: threeComponentDefinitions.GaussianSplat,
    OrbitControls: threeComponentDefinitions.OrbitControls,
  },
  actions: {},
});

const { registry } = defineRegistry(catalog, {
  components: {
    Box: threeComponents.Box,
    Sphere: threeComponents.Sphere,
    AmbientLight: threeComponents.AmbientLight,
    DirectionalLight: threeComponents.DirectionalLight,
    GaussianSplat: threeComponents.GaussianSplat,
    OrbitControls: threeComponents.OrbitControls,
  },
});

<ThreeCanvas
  spec={spec}
  registry={registry}
  shadows
  camera={{ position: [5, 5, 5], fov: 50 }}
  style={{ width: "100%", height: "100vh" }}
/>;

Next.js (Full Apps)

import type { NextAppSpec } from "@json-render/next";
import { createNextApp } from "@json-render/next/server";
import { NextAppProvider } from "@json-render/next";

const spec: NextAppSpec = {
  metadata: { title: { default: "My App", template: "%s | My App" } },
  layouts: {
    main: {
      root: "shell",
      elements: {
        shell: { type: "Container", props: {}, children: ["nav", "slot"] },
        nav: { type: "NavBar", props: {}, children: [] },
        slot: { type: "Slot", props: {}, children: [] },
      },
    },
  },
  routes: {
    "/": {
      layout: "main",
      metadata: { title: "Home" },
      page: {
        root: "hero",
        elements: {
          hero: { type: "Card", props: { title: "Welcome" }, children: [] },
        },
      },
    },
  },
};

// Server: creates Page, generateMetadata, generateStaticParams
const app = createNextApp({ spec });

// Client: wrap your layout with NextAppProvider
// <NextAppProvider registry={registry} handlers={handlers}>
//   {children}
// </NextAppProvider>

TanStack Start (Full Apps)

import { createFileRoute, notFound } from "@tanstack/react-router";
import {
  PageRenderer,
  StartErrorBoundary,
  StartLoading,
  StartNotFound,
  type StartAppSpec,
} from "@json-render/tanstack-start";
import { createStartApp } from "@json-render/tanstack-start/server";

const spec: StartAppSpec = {
  metadata: { title: { default: "My App", template: "%s | My App" } },
  routes: {
    "/": {
      metadata: { title: "Home" },
      page: {
        root: "hero",
        elements: {
          hero: { type: "Card", props: { title: "Welcome" }, children: [] },
        },
      },
    },
  },
};

const { getPageData, getHead } = createStartApp({ spec });

export const Route = createFileRoute("/$")({
  loader: async ({ location }) => {
    const data = await getPageData({ pathname: location.pathname });
    if (!data) throw notFound();
    return data;
  },
  head: ({ match }) => getHead({ pathname: match.pathname }),
  component: () => <PageRenderer {...Route.useLoaderData()} />,
  pendingComponent: StartLoading,
  errorComponent: StartErrorBoundary,
  notFoundComponent: StartNotFound,
});

Wrap the root route's outlet with <StartAppProvider spec={spec}> so route fallback components can resolve the current route. Pass named $computed implementations through its functions prop.

shadcn-svelte (Svelte)

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

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

// In your Svelte component:
// <Renderer spec={spec} registry={registry} />

Devtools

Drop-in inspector panel for any json-render app. Spec tree, state editor, action log, stream log, catalog browser, DOM picker.

// React
import { JsonRenderDevtools } from "@json-render/devtools-react";

<JSONUIProvider registry={registry} handlers={handlers}>
  <Renderer spec={spec} registry={registry} />
  <JsonRenderDevtools spec={spec} catalog={catalog} messages={messages} />
</JSONUIProvider>;

Floating toggle appears bottom-right. Hotkey: Ctrl/Cmd + Shift + J. Tree-shakes to null in production.

Available for React, Vue, Svelte, and Solid — swap @json-render/devtools-react for the adapter that matches your renderer.

Ink (Terminal)

import { defineCatalog } from "@json-render/core";
import {
  schema,
  standardComponentDefinitions,
  standardActionDefinitions,
  defineRegistry,
  Renderer,
  JSONUIProvider,
} from "@json-render/ink";

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

const { registry } = defineRegistry(catalog, { components: {} });

const spec = {
  root: "card-1",
  elements: {
    "card-1": {
      type: "Card",
      props: { title: "Status" },
      children: ["status-1"],
    },
    "status-1": {
      type: "StatusLine",
      props: { label: "Build", status: "success" },
      children: [],
    },
  },
};

<JSONUIProvider initialState={{}}

json-render (vercel-labs/json-render)

Searching Database…

18.7K ·GitHub
Json-render
这是什么？json-render 是一个生成式 UI 框架：AI 根据自然语言提示生成界面，但输出受限于你定义的组件目录。这样你既能保证可靠性和可预测性，又能让 AI 驱动界面。
这是一个渲染库，还是一整套包？它是一个由多个独立 npm 包组成的生态，围绕共享的 JSON 规范构建：包括负责结构定义与组件目录的核心包，以及分别面向 React、Vue、Svelte、Solid、React Native、Next.js、TanStack Start、Remotion、React PDF、React Email、Ink（终端）和 Three.js 的专用渲染器，另外还有开发者工具和状态存储适配器。
我怎样在自己的应用里跑起来？先用 defineCatalog 定义允许使用的组件目录，再为你的渲染器实现这些组件，最后把 AI 生成的 JSON 规范传给 JSONUIProvider/Renderer 等提供者来渲染。
一定要用 shadcn/ui 组件吗？能用自己的组件吗？不会被绑定：@json-render/shadcn 提供了 36 个开箱即用的 shadcn/ui 组件（基于 Radix UI 和 Tailwind CSS），但你也可以为任何渲染器从零定义自己的组件目录。
AI 想生成什么界面都可以吗，还是有限制？AI 只能输出你所定义组件目录中已存在的组件，而且生成的 JSON 每次都必须符合你的结构定义。这是保证输出可预测的核心护栏。
同一份 AI 生成的规范能用在网页、移动端等多个平台吗？可以，同一套组件目录和 JSON 规范可以交给不同平台的专用渲染器来渲染：网页框架（React、Vue、Svelte、Solid）、用于移动端的 React Native，甚至还包括 PDF、邮件、视频（Remotion）和终端界面（Ink）等非界面类目标。
开发者工具能给我带来什么？一个开箱即用的检查面板（按 Ctrl/Cmd+Shift+J 切换），可显示规范树、状态编辑器、操作日志、流式日志、组件目录浏览器和 DOM 拾取器；在生产构建中会被摇树优化去除，结果为 null。
json-render 能生成网页之外的东西，比如 PDF 或视频吗？可以。专用渲染器支持 React PDF（文档）、React Email（邮件）、Remotion（视频），还有一个 Image 渲染器可输出 SVG/PNG（例如 OG 图片）。
它能直接和 Claude、ChatGPT 这类 AI 助手集成吗？可以，@json-render/mcp 包提供了 MCP Apps 集成，因此规范可以在 Claude、ChatGPT、Cursor 和 VS Code 中渲染。
它支持哪些状态管理库？提供了 Redux/Redux Toolkit、Zustand、Jotai 和 XState Store 的适配器，它们都接入框架的 StateStore 接口。
What are similar projects?ui, CopilotKit, canvas-ui, formily, ui-ux-pro-max-skill, blobatar, cult-ui, plate
Which topics is it in?generative-ui, radix-ui, shadcn-ui, svelte, state-management, react-native, tailwindcss, component-library, tui, nextjs, streaming, vue
Creator
vercel-labs
Size
6.2 MB
Stars
18.7K
Updated
CommitOct 13Releasev0.21.1Oct 13
Age
9mo
Commits · 90 Days