json-render

https://json-render.dev/docs
Admin
json-render is a framework for building generative UI applications where AI generates type-safe,...
Tokens:107,116
Snippets:653
Trust Score:6.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install @json-render/image

Source: https://json-render.dev/docs/api/image

Install the core and image packages. For PNG output, also install the optional peer dependency @resvg/resvg-js.

```bash
npm install @json-render/core @json-render/image
```

```bash
npm install @resvg/resvg-js
```

--------------------------------

### Install

Source: https://json-render.dev/docs/api/image

Install the @json-render/image package and its core dependency. For PNG output, also install the optional peer dependency @resvg/resvg-js.

```APIDOC
## Install
```
npm install @json-render/core @json-render/image
```

For PNG output, also install the optional peer dependency:
```
npm install @resvg/resvg-js
```
```

--------------------------------

### Install @json-render/next

Source: https://json-render.dev/docs/api/next

Install the core, react, and next packages for @json-render.

```bash
npm install @json-render/core @json-render/react @json-render/next
```

--------------------------------

### Vue 3 Renderer Setup with Custom Components

Source: https://json-render.dev/docs/changelog

Example of setting up the Vue 3 renderer with custom components. It demonstrates defining a registry and using the `h` function for component creation.

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

--------------------------------

### Setup Standalone Mode

Source: https://json-render.dev/docs/generation-modes

Configure the system prompt for standalone mode, which is the default. Use custom rules to guide the AI's UI structure.

```typescript
import { streamText } from "ai";

// Standalone mode is the default (no mode option needed)
const systemPrompt = catalog.prompt({
  customRules: [
    "Use Card as root for forms and small UIs.",
    "Use Grid for multi-column layouts.",
  ],
});

const result = streamText({
  model: "anthropic/claude-haiku-4.5",
  system: systemPrompt,
  prompt: userPrompt,
});
```

--------------------------------

### Install Devtools for Solid

Source: https://json-render.dev/docs/devtools

Install the Solid adapter for json-render devtools using npm.

```bash
npm install @json-render/devtools @json-render/devtools-solid
```

--------------------------------

### Install Core and Solid Packages

Source: https://json-render.dev/docs/api/solid

Install the core and SolidJS packages for json-render. Ensure you have SolidJS and Zod installed as peer dependencies.

```bash
npm install @json-render/core @json-render/solid
```

```bash
npm install solid-js zod
```

--------------------------------

### Install @json-render/core and @json-render/react-pdf

Source: https://json-render.dev/docs/api/react-pdf

Install the core and React PDF packages using npm.

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

--------------------------------

### Install @json-render/core and @json-render/ink

Source: https://json-render.dev/docs/api/ink

Install the core and Ink packages using npm.

```bash
npm install @json-render/core @json-render/ink
```

--------------------------------

### Install json-render Core Skill

Source: https://json-render.dev/docs/skills

Installs the core skill for json-render, which is essential for defining catalogs, schemas, and generating AI prompts. This is the starting point for any json-render project.

```bash
npx skills add vercel-labs/json-render --skill core
```

--------------------------------

### Install json-render Core and React UI

Source: https://json-render.dev/docs/installation

Install the core package along with the React renderer. Ensure you have React and Zod installed as peer dependencies.

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

```bash
npm install react zod
```

--------------------------------

### Install Devtools for React

Source: https://json-render.dev/docs/devtools

Install the React adapter for json-render devtools using npm.

```bash
npm install @json-render/devtools @json-render/devtools-react
```

--------------------------------

### Install @json-render/core and @json-render/svelte

Source: https://json-render.dev/docs/api/svelte

Install the core library and the Svelte integration package using npm.

```bash
npm install @json-render/core @json-render/svelte
```

--------------------------------

### Install json-render Core, Remotion, and Player

Source: https://json-render.dev/docs/installation

Install the core package, Remotion renderer, and Remotion player for video creation.

```bash
npm install @json-render/core @json-render/remotion remotion @remotion/player
```

--------------------------------

### Install @json-render/xstate

Source: https://json-render.dev/docs/api/xstate

Install the necessary packages for using @json-render/xstate with json-render and React.

```bash
npm install @json-render/xstate @json-render/core @json-render/react @xstate/store
```

--------------------------------

### Install @json-render/xstate and @xstate/store

Source: https://json-render.dev/docs/changelog

Install the necessary packages for integrating XState with json-render's StateStore interface.

```bash
npm install @json-render/xstate @xstate/store
```

--------------------------------

### Install React, Ink, and Zod

Source: https://json-render.dev/docs/api/ink

Install the peer dependencies required for @json-render/ink.

```bash
npm install react ink zod
```

--------------------------------

### Install @json-render/react-three-fiber

Source: https://json-render.dev/docs/api/react-three-fiber

Install the package and its dependencies using npm.

```bash
npm install @json-render/react-three-fiber @json-render/core @json-render/react @react-three/fiber @react-three/drei three zod
```

--------------------------------

### Install json-render Adapter for XState

Source: https://json-render.dev/docs/installation

Install the adapter to integrate json-render with XState for external state management.

```bash
npm install @json-render/xstate
```

--------------------------------

### Install @json-render/next

Source: https://json-render.dev/docs/changelog

Install the Next.js renderer to build full Next.js applications from JSON specs.

```bash
npm install @json-render/next
```

--------------------------------

### Install json-render Core, React UI, and shadcn/ui

Source: https://json-render.dev/docs/installation

Install the core package, React renderer, and shadcn/ui components for faster prototyping. Requires Tailwind CSS.

```bash
npm install @json-render/core @json-render/react @json-render/shadcn
```

--------------------------------

### Install @json-render/shadcn-svelte

Source: https://json-render.dev/docs/changelog

Install the shadcn-svelte components for building Svelte apps with json-render.

```bash
npm install @json-render/shadcn-svelte
```

--------------------------------

### Install @json-render/directives

Source: https://json-render.dev/docs/api/directives

Install the directives package using npm.

```bash
npm install @json-render/directives
```

--------------------------------

### Install Devtools for Vue

Source: https://json-render.dev/docs/devtools

Install the Vue adapter for json-render devtools using npm.

```bash
npm install @json-render/devtools @json-render/devtools-vue
```

--------------------------------

### Install @json-render/shadcn-svelte

Source: https://json-render.dev/docs/api/shadcn-svelte

Install the shadcn-svelte package along with its core dependencies.

```bash
npm install @json-render/shadcn-svelte @json-render/core @json-render/svelte zod
```

--------------------------------

### Install shadcn/ui Components for json-render

Source: https://json-render.dev/docs/changelog

Install the shadcn/ui integration package for json-render to utilize pre-built components.

```bash
npm install @json-render/shadcn
```

--------------------------------

### Install json-render Adapter for Jotai

Source: https://json-render.dev/docs/installation

Install the adapter to integrate json-render with Jotai for external state management.

```bash
npm install @json-render/jotai
```

--------------------------------

### Install Devtools for Svelte

Source: https://json-render.dev/docs/devtools

Install the Svelte adapter for json-render devtools using npm.

```bash
npm install @json-render/devtools @json-render/devtools-svelte
```

--------------------------------

### Install json-render MCP Skill

Source: https://json-render.dev/docs/skills

Installs the MCP skill for json-render, enabling AI agents to build MCP Apps that serve json-render UIs within AI tools like Claude, ChatGPT, Cursor, and VS Code. This skill covers MCP server setup, tool definitions, and UI streaming.

```bash
npx skills add vercel-labs/json-render --skill mcp
```

--------------------------------

### Install Vercel AI SDK for AI Integration

Source: https://json-render.dev/docs/installation

Install the Vercel AI SDK to use json-render with AI models.

```bash
npm install ai
```

--------------------------------

### Install @json-render/zustand

Source: https://json-render.dev/docs/api/zustand

Install the necessary packages for @json-render/zustand, including core, react, and zustand.

```bash
npm install @json-render/zustand @json-render/core @json-render/react zustand
```

--------------------------------

### Install @json-render/jotai Dependencies

Source: https://json-render.dev/docs/api/jotai

Install the necessary packages for using the Jotai adapter with json-render.

```bash
npm install @json-render/jotai @json-render/core @json-render/react jotai
```

--------------------------------

### Install @json-render/redux

Source: https://json-render.dev/docs/api/redux

Install the package and its dependencies. Redux Toolkit is recommended for a better Redux experience.

```bash
npm install @json-render/redux @json-render/core @json-render/react redux
# or with Redux Toolkit (recommended):
npm install @json-render/redux @json-render/core @json-render/react @reduxjs/toolkit
```

--------------------------------

### App Component Setup with Providers

Source: https://json-render.dev/docs/registry

Wire up the application using `StateProvider`, `VisibilityProvider`, and `ActionProvider` along with the `Renderer` component.

```typescript
import { useMemo, useRef } from 'react';
import {
  Renderer,
  StateProvider,
  VisibilityProvider,
  ActionProvider,
} from '@json-render/react';
import { registry, handlers } from './registry';

function App({ spec, state, setState }) {
  const stateRef = useRef(state);
  const setStateRef = useRef(setState);
  stateRef.current = state;
  setStateRef.current = setState;

  const actionHandlers = useMemo(
    () => handlers(() => setStateRef.current, () => stateRef.current),
    [],
  );

  return (
    <StateProvider initialState={state}>
      <VisibilityProvider>
        <ActionProvider handlers={actionHandlers}>
          <Renderer spec={spec} registry={registry} />
        </ActionProvider>
      </VisibilityProvider>
    </StateProvider>
  );
}
```

--------------------------------

### Install json-render Adapter for Zustand

Source: https://json-render.dev/docs/installation

Install the adapter to integrate json-render with Zustand for external state management.

```bash
npm install @json-render/zustand
```

--------------------------------

### Install @json-render/ink

Source: https://json-render.dev/docs/changelog

Install the Ink terminal renderer to create terminal UIs from JSON specs.

```bash
npm install @json-render/ink
```

--------------------------------

### Install @json-render/solid

Source: https://json-render.dev/docs/changelog

Install the SolidJS renderer for json-render. This enables reactive rendering of JSON specs into Solid components.

```bash
npm install @json-render/core @json-render/solid
```

--------------------------------

### Install json-render Core and React Native

Source: https://json-render.dev/docs/installation

Install the core package along with the React Native renderer.

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

--------------------------------

### Install AI SDK and json-render React Package

Source: https://json-render.dev/docs/ai-sdk

Install the necessary packages for AI SDK and json-render React integration.

```bash
npm install ai @ai-sdk/react
```

--------------------------------

### Install @json-render/mcp

Source: https://json-render.dev/docs/changelog

Install the MCP Apps integration for json-render. This enables serving json-render UIs as interactive apps within MCP-capable clients.

```bash
npm install @json-render/mcp
```

--------------------------------

### Install MCP and React dependencies

Source: https://json-render.dev/docs/api/mcp

Install the necessary packages for MCP integration and the React UI for the iframe.

```bash
npm install @json-render/mcp @json-render/core @modelcontextprotocol/sdk
```

```bash
npm install @json-render/react react react-dom
```

--------------------------------

### Install json-render Core and Vue

Source: https://json-render.dev/docs/installation

Install the core package and the Vue renderer. Vue and Zod are required as peer dependencies.

```bash
npm install @json-render/core @json-render/vue
```

```bash
npm install vue zod
```

--------------------------------

### Install @json-render/react-email

Source: https://json-render.dev/docs/api/react-email

Install the core package, the react-email renderer, and the necessary React Email dependencies.

```bash
npm install @json-render/core @json-render/react-email @react-email/components @react-email/render
```

--------------------------------

### Install json-render Adapter for Redux

Source: https://json-render.dev/docs/installation

Install the adapter to integrate json-render with Redux for external state management.

```bash
npm install @json-render/redux
```

--------------------------------

### Install @json-render/image

Source: https://json-render.dev/docs/changelog

Install the server-side image renderer for json-render, powered by Satori. This package converts JSON specs into SVG or PNG output.

```bash
npm install @json-render/image
```

--------------------------------

### Install @json-render/devtools-react

Source: https://json-render.dev/docs/changelog

Install the React devtools package to enable browser inspection of json-render applications.

```bash
npm install @json-render/devtools-react
```

--------------------------------

### Install json-render Core and Svelte

Source: https://json-render.dev/docs/installation

Install the core package with the Svelte renderer. Svelte and Zod are required as peer dependencies.

```bash
npm install @json-render/core @json-render/svelte
```

```bash
npm install svelte zod
```

--------------------------------

### Install @json-render/shadcn and Dependencies

Source: https://json-render.dev/docs/api/shadcn

Install the shadcn/ui components for json-render along with core, react, and zod. Ensure Tailwind CSS is configured in your project.

```bash
npm install @json-render/shadcn @json-render/core @json-render/react zod
```

--------------------------------

### Install json-render XState Skill

Source: https://json-render.dev/docs/skills

Installs the XState skill for json-render, offering an adapter for json-render's `StateStore` interface with XState. This facilitates state management integration using XState.

```bash
npx skills add vercel-labs/json-render --skill xstate
```

--------------------------------

### Install json-render Jotai Skill

Source: https://json-render.dev/docs/skills

Installs the Jotai skill for json-render, providing an adapter for json-render's `StateStore` interface with Jotai. This enables state management integration using Jotai.

```bash
npx skills add vercel-labs/json-render --skill jotai
```

--------------------------------

### Install json-render Zustand Skill

Source: https://json-render.dev/docs/skills

Installs the Zustand skill for json-render, offering an adapter for json-render's `StateStore` interface with Zustand. This facilitates state management integration using Zustand.

```bash
npx skills add vercel-labs/json-render --skill zustand
```

--------------------------------

### Install json-render Remotion Skill

Source: https://json-render.dev/docs/skills

Installs the Remotion skill for json-render, allowing AI agents to generate videos from JSON timeline specs. This skill covers compositions, sequences, timeline structure, and video rendering.

```bash
npx skills add vercel-labs/json-render --skill remotion
```

--------------------------------

### Install json-render Solid Skill

Source: https://json-render.dev/docs/skills

Installs the Solid skill for json-render, enabling AI agents to render JSON specs as SolidJS component trees. This skill covers Solid-specific reactive patterns, provider wiring, bindings, actions, and streaming.

```bash
npx skills add vercel-labs/json-render --skill solid
```

--------------------------------

### Install json-render Shadcn Skill

Source: https://json-render.dev/docs/skills

Installs the shadcn/ui skill for json-render, allowing AI agents to utilize pre-built shadcn/ui components. This skill integrates Radix UI primitives and Tailwind styling.

```bash
npx skills add vercel-labs/json-render --skill shadcn
```

--------------------------------

### Install @json-render/yaml

Source: https://json-render.dev/docs/changelog

Install the YAML wire format package for json-render. This package includes a streaming YAML parser and utilities for system prompts and AI SDK transforms.

```bash
npm install @json-render/yaml
```

--------------------------------

### Install json-render Redux Skill

Source: https://json-render.dev/docs/skills

Installs the Redux skill for json-render, providing an adapter for json-render's `StateStore` interface with Redux. This allows for state management integration using Redux.

```bash
npx skills add vercel-labs/json-render --skill redux
```

--------------------------------

### Quick Start: Add Devtools to React App

Source: https://json-render.dev/docs/devtools

Drop the JsonRenderDevtools component within your JSONUIProvider to enable the devtools panel. This setup allows for immediate inspection of your application's spec and state.

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

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

--------------------------------

### Install json-render Image Skill

Source: https://json-render.dev/docs/skills

Installs the Image skill for json-render, enabling AI agents to convert JSON specs into SVG and PNG images via Satori. This skill covers the image-specific registry, dimensions, fonts, and rendering options.

```bash
npx skills add vercel-labs/json-render --skill image
```

--------------------------------

### Install json-render React-PDF Skill

Source: https://json-render.dev/docs/skills

Installs the React-PDF skill for json-render, allowing AI agents to generate PDFs from JSON specs using `@react-pdf/renderer`. This skill includes a PDF-specific component registry and covers page layout and styling.

```bash
npx skills add vercel-labs/json-render --skill react-pdf
```

--------------------------------

### Standalone Generation Mode Setup

Source: https://json-render.dev/docs/generation-modes

In standalone mode, the default prompt behavior is to output only JSONL. Use `catalog.prompt()` for this mode.

```javascript
catalog.prompt()
```

--------------------------------

### Link Component Example

Source: https://json-render.dev/docs/api/next

A client-side navigation component that wraps next/link.

```json
{ "type": "Link", "props": { "href": "/about" }, "children": ["link-text"] }
```

--------------------------------

### Build Edit Instructions

Source: https://json-render.dev/docs/api/core

Generate the prompt section describing available edit modes. This example configures instructions for 'patch' and 'merge' modes in JSON format.

```typescript
import {
  buildEditInstructions,
  type EditMode,
  type EditConfig,
} from '@json-render/core';

type EditMode = "patch" | "merge" | "diff";

function buildEditInstructions(config: EditConfig, format: "json" | "yaml"): string

const instructions = buildEditInstructions({ modes: ["patch", "merge"] }, "json");
```

--------------------------------

### ActionProvider Setup

Source: https://json-render.dev/docs/api/react-native

Wrap your application with ActionProvider to handle custom actions defined in your specs. Provide a map of handlers for different action types.

```jsx
<ActionProvider handlers={Record<string, ActionHandler>}>
  {children}
</ActionProvider>
```

--------------------------------

### Install Svelte and Zod Peer Dependencies

Source: https://json-render.dev/docs/api/svelte

Ensure Svelte and Zod are installed as they are peer dependencies for @json-render/svelte.

```bash
npm install svelte zod
```

--------------------------------

### Standalone Component Example

Source: https://json-render.dev/docs/code-export

Example of a generated component that is standalone and receives data as props, without json-render dependencies.

```typescript
// Generated component (standalone)
interface MetricProps {
  label: string;
  statePath: string;
  data?: Record<string, unknown>;
}

export function Metric({ label, statePath, data }: MetricProps) {
  const value = data ? getByPath(data, statePath) : undefined;
  return (
    <div>
      <span>{label}</span>
      <span>{formatValue(value)}</span>
    </div>
  );
}
```

--------------------------------

### Migrate Catalog Creation: createCatalog to defineCatalog

Source: https://json-render.dev/docs/migration

Replaced `createCatalog` and `generateSystemPrompt` with `defineSchema` + `defineCatalog`. Ensure you import `defineCatalog` and use the new structure for creating catalogs and generating prompts.

```javascript
import { createCatalog, generateSystemPrompt } from "@json-render/core";

const catalog = createCatalog({
  name: "my-app",
  components: { /* ... */ },
  actions: { /* ... */ },
});

const prompt = generateSystemPrompt(catalog);
```

```javascript
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/react/schema";

const catalog = defineCatalog(schema, {
  components: { /* ... */ },
  actions: { /* ... */ },
});

const prompt = catalog.prompt();

// Inline mode prompt (formerly "chat")
const inlinePrompt = catalog.prompt({ mode: "inline" });
```

--------------------------------

### Install @json-render/react-email

Source: https://json-render.dev/docs/changelog

Install the React Email renderer for json-render. Use this to generate HTML and plain-text emails from JSON specifications.

```bash
npm install @json-render/react-email
```

--------------------------------

### Get Array Length with $count

Source: https://json-render.dev/docs/api/directives

Use the $count directive to get the length of an array or string. Returns 0 for other types.

```json
{ "$count": { "$state": "/cart/items" } }
```

--------------------------------

### Install @json-render/vue

Source: https://json-render.dev/docs/changelog

Install the Vue 3 renderer for json-render. This provides full feature parity with the React renderer for Vue applications.

```bash
npm install @json-render/core @json-render/vue
```

--------------------------------

### Create a Custom Renderer with Directives

Source: https://json-render.dev/docs/directives

Shows an alternative way to set up a renderer using `createRenderer`, passing both catalog and components, and then applying custom directives to the created renderer instance.

```jsx
const MyRenderer = createRenderer(catalog, components);

<MyRenderer spec={spec} directives={directives} />
```

--------------------------------

### Define Catalog and Registry

Source: https://json-render.dev/docs/api/react-three-fiber

Define a catalog with three-dimensional components and set up the registry for rendering. This example includes Box, Sphere, AmbientLight, DirectionalLight, and OrbitControls.

```javascript
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,
    OrbitControls: threeComponentDefinitions.OrbitControls,
  },
  actions: {},
});

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

--------------------------------

### Get Current Repeat Index with $index

Source: https://json-render.dev/docs/data-binding

Use the $index expression inside a repeat to get the current array index (zero-based number).

```json
{
  "type": "Text",
  "props": { "content": { "$index": true } },
  "children": []
}
```

--------------------------------

### AI-Generated JSON Spec Example

Source: https://json-render.dev/docs

An example of a JSON specification generated by AI, detailing the structure and properties of UI elements based on a defined catalog.

```json
{
  "root": "card-1",
  "elements": {
    "card-1": {
      "type": "Card",
      "props": { "title": "Revenue Dashboard" },
      "children": ["metric-1", "metric-2"]
    },
    "metric-1": {
      "type": "Metric",
      "props": { "label": "Total Revenue", "value": "$48,200" }
    },
    "metric-2": {
      "type": "Metric",
      "props": { "label": "Growth", "value": "+12%" }
    }
  }
}
```

--------------------------------

### Import xstateStoreStateStore

Source: https://json-render.dev/docs/api/xstate

Import the xstateStoreStateStore function from the @json-render/xstate package.

```javascript
import { xstateStoreStateStore } from "@json-render/xstate";
```

--------------------------------

### Create XState Store for json-render

Source: https://json-render.dev/docs/api/xstate

Create a StateStore backed by an @xstate/store atom. The atom should hold the json-render state model.

```javascript
import { createAtom } from "@xstate/store";
import { xstateStoreStateStore } from "@json-render/xstate";
import { StateProvider } from "@json-render/react";

const uiAtom = createAtom({ count: 0 });
const store = xstateStoreStateStore({ atom: uiAtom });
```

--------------------------------

### Install @json-render/react-three-fiber

Source: https://json-render.dev/docs/changelog

Install the React Three Fiber renderer for json-render. This allows JSON specs to be rendered as 3D scenes using React Three Fiber.

```bash
npm install @json-render/react-three-fiber
```

--------------------------------

### Generate Prompt with Directives

Source: https://json-render.dev/docs/directives

Illustrates how to generate a system prompt for AI, including custom directives, by calling the `prompt` method on the catalog object and passing the directives.

```javascript
const prompt = catalog.prompt({ directives });
```

--------------------------------

### Build User Prompt for Fresh Generation

Source: https://json-render.dev/docs/api/core

Construct a user prompt for AI generation. This example shows a basic prompt for creating a new application.

```typescript
import { buildUserPrompt } from '@json-render/core';

const userPrompt = buildUserPrompt({ prompt: "create a todo app" });
```

--------------------------------

### createMcpApp

Source: https://json-render.dev/docs/api/mcp

Create a fully-configured MCP server. This is the main entry point for setting up a json-render MCP application.

```APIDOC
## createMcpApp

### Description
Create a fully-configured MCP server. This is the main entry point.

### Method
```javascript
import { createMcpApp } from "@json-render/mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import fs from "node:fs";

const server = createMcpApp({
  name: "My Dashboard",
  version: "1.0.0",
  catalog: myCatalog,
  html: fs.readFileSync("dist/index.html", "utf-8"),
});

await server.connect(new StdioServerTransport());
```

### Options
#### CreateMcpAppOptions
- `name` (string) - Required - Server name shown in client UIs
- `version` (string) - Required - Server version
- `catalog` (Catalog) - Required - json-render catalog defining available components
- `html` (string) - Required - Self-contained HTML for the iframe UI
- `tool` (McpToolOptions) - Optional - Tool name/title/description overrides
```

--------------------------------

### Directive Composition Example

Source: https://json-render.dev/docs/directives

An example of directive composition where a '$format' directive wraps a '$math' directive, which in turn uses a '$state' expression. This shows how directives can be nested and resolve values from state.

```json
{
  "$format": "currency",
  "value": {
    "$math": "multiply",
    "a": { "$state": "/price" },
    "b": { "$state": "/qty" }
  },
  "currency": "USD"
}
```

--------------------------------

### Catalog Instance Methods

Source: https://json-render.dev/docs/api/core

The Catalog instance provides methods for AI prompt generation, validation, and schema export.

```APIDOC
## Catalog Instance Methods

The returned catalog provides methods for AI prompt generation, validation, and schema export:

### `prompt(options?: PromptOptions): string`
Generates an AI system prompt based on the catalog configuration and provided options.

### `validate(spec: unknown): SpecValidationResult`
Validates a given specification against the catalog's schema.

### `zodSchema(): z.ZodType`
Returns the Zod schema for the catalog's specifications.

### `jsonSchema(): object`
Exports the catalog's schema as a JSON Schema object.

### Example Usage
```typescript
// Generate AI system prompt
const systemPrompt = catalog.prompt({
  customRules: ["Always use Card as root element"],
});

// Validate a spec from AI
const result = catalog.validate(aiOutput);
if (result.success) {
  render(result.data);
} else {
  console.error(result.error);
}

// Get Zod schema for custom validation
const schema = catalog.zodSchema();
const parsed = schema.safeParse(aiOutput);

// Export as JSON Schema (for structured outputs)
const jsonSchema = catalog.jsonSchema();
```
```

--------------------------------

### Example A2UI Message Structure

Source: https://json-render.dev/docs/a2ui

This is an example of an A2UI message using an adjacency list model. It includes components like Text, DateTimeInput, and Button, with ID references for easy patching.

```json
{
  "surfaceUpdate": {
    "surfaceId": "main",
    "components": [
      {
        "id": "header",
        "component": {
          "Text": {
            "text": {"literalString": "Book Your Table"},
            "usageHint": "h1"
          }
        }
      },
      {
        "id": "date-picker",
        "component": {
          "DateTimeInput": {
            "label": {"literalString": "Select Date"},
            "value": {"path": "/reservation/date"},
            "enableDate": true
          }
        }
      },
      {
        "id": "submit-btn",
        "component": {
          "Button": {
            "child": "submit-text",
            "action": {"name": "confirm_booking"}
          }
        }
      },
      {
        "id": "submit-text",
        "component": {
          "Text": {"text": {"literalString": "Confirm Reservation"}}
        }
      }
    ]
  }
}
```

--------------------------------

### Define Catalog with Components and Actions

Source: https://json-render.dev/docs/catalog

Use `defineCatalog` from `@json-render/core` to create a catalog. Define components with their props schemas using Zod, and actions with their parameters. The schema import is framework-specific.

```javascript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react/schema'; // or '@json-render/react-native/schema'
import { z } from 'zod';

const catalog = defineCatalog(schema, {
  components: {
    // Define each component with its props schema
    Card: {
      props: z.object({
        title: z.string(),
        description: z.string().nullable(),
        padding: z.enum(['sm', 'md', 'lg']).nullable(),
      }),
      slots: ["default"], // Can contain other components
      description: "Container card for grouping content",
    },
    
    Metric: {
      props: z.object({
        label: z.string(),
        value: z.union([z.string(), z.number()]),
        format: z.enum(['currency', 'percent', 'number']),
      }),
      description: "Display a single metric value",
    },
  },
  
actions: {
    submit_form: {
      params: z.object({
        formId: z.string(),
      }),
      description: 'Submit a form',
    },
    
    export_data: {
      params: z.object({
        format: z.enum(['csv', 'pdf', 'json']),
      }),
      description: 'Export data in various formats',
    },
  },
});
```

--------------------------------

### Install json-render React-Email Skill

Source: https://json-render.dev/docs/skills

Installs the React-Email skill for json-render, enabling AI agents to render JSON specs as HTML or plain-text emails. This skill features an email-specific registry and rendering pipeline.

```bash
npx skills add vercel-labs/json-render --skill react-email
```

--------------------------------

### Set up JsonUIProvider for State and Actions

Source: https://json-render.dev/docs/api/svelte

The JsonUIProvider wraps components, providing state management, visibility, validation, and action handling. It requires initial state and handler configurations.

```svelte
<JsonUIProvider
  initialState={{}}
  handlers={handlers}
  validationFunctions={validationFunctions}
>
  <Renderer {spec} {registry} />
</JsonUIProvider>
```

--------------------------------

### Install json-render Codegen Skill

Source: https://json-render.dev/docs/skills

Installs the Codegen skill for json-render, teaching AI agents how to export UI specs as framework-specific source code. This skill covers the codegen pipeline and custom exporter creation.

```bash
npx skills add vercel-labs/json-render --skill codegen
```

--------------------------------

### Create a Redux-backed StateStore

Source: https://json-render.dev/docs/api/redux

Configure and create a `StateStore` instance using Redux. This involves providing the Redux store, a selector to isolate the json-render state slice, and a dispatch function to update it.

```javascript
import { configureStore, createSlice } from "@reduxjs/toolkit";
import { reduxStateStore } from "@json-render/redux";
import { StateProvider } from "@json-render/react";

const uiSlice = createSlice({
  name: "ui",
  initialState: { count: 0 } as Record<string, unknown>,
  reducers: {
    replaceUiState: (_state, action) => action.payload,
  },
});

const reduxStore = configureStore({
  reducer: { ui: uiSlice.reducer },
});

const store = reduxStateStore({
  store: reduxStore,
  selector: (state) => state.ui,
  dispatch: (next, s) => s.dispatch(uiSlice.actions.replaceUiState(next)),
});
```

```javascript
<StateProvider store={store}>
  {/* json-render reads/writes go through Redux */}
</StateProvider>
```

--------------------------------

### Install json-render Svelte Skill

Source: https://json-render.dev/docs/skills

Installs the Svelte skill for json-render, allowing AI agents to render JSON specs as Svelte 5 component trees. This skill covers the Svelte renderer API and component registration.

```bash
npx skills add vercel-labs/json-render --skill svelte
```

--------------------------------

### Setup Inline Mode

Source: https://json-render.dev/docs/generation-modes

Enable inline mode by setting the `mode` option to 'inline' in the system prompt. This mode allows for conversational responses alongside UI patches.

```typescript
import { streamText } from "ai";
import { pipeJsonRender } from "@json-render/core";
import { createUIMessageStream, createUIMessageStreamResponse } from "ai";

// Enable inline mode
const systemPrompt = catalog.prompt({ mode: "inline" });

const result = streamText({
  model: yourModel,
  system: systemPrompt,
  messages,
});

// In your API route, pipe the stream through pipeJsonRender
// to separate text from JSONL patches
const stream = createUIMessageStream({
  execute: async ({ writer }) => {
    writer.merge(pipeJsonRender(result.toUIMessageStream()));
  },
});

return createUIMessageStreamResponse({ stream });
```

--------------------------------

### Install json-render React-Native Skill

Source: https://json-render.dev/docs/skills

Installs the React Native skill for json-render, empowering AI agents to render JSON specs as native mobile UIs. This skill includes the native component registry and addresses platform-specific considerations.

```bash
npx skills add vercel-labs/json-render --skill react-native
```

--------------------------------

### SolidJS Renderer Setup

Source: https://json-render.dev/docs/renderers

Implement the SolidJS renderer for fine-grained reactivity and state bindings. This renderer supports validation, visibility, and event-driven actions, translating JSON specs into SolidJS component trees.

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

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

--------------------------------

### Install json-render React Skill

Source: https://json-render.dev/docs/skills

Installs the React skill for json-render, enabling AI agents to render JSON specs as React component trees. This skill supports custom component registries, client-side interactivity, and state management.

```bash
npx skills add vercel-labs/json-render --skill react
```
Tokens:
Raw