The Problem
Developers building AI‑driven UI generators need a way to guarantee that the model’s output stays within a known component set, validates against a schema, and can be streamed to the client without exposing arbitrary code. Without such guardrails the UI can be unpredictable, insecure, or require costly post‑processing.
What This Does
json-render provides a catalog‑first approach: you define a component catalog with Zod schemas (packages/core/src/catalog.ts) and the library validates incoming JSON against that catalog. The core runtime (packages/core/src/) handles visibility rules, data binding, and action handling, while the React renderer (packages/react/src/renderer.tsx) walks the validated tree and renders registered components. Example implementations live in apps/web/components/demo/ and examples/dashboard/components/ui/, showing how a component registry maps JSON type fields to real React components.
The repo is a monorepo managed by pnpm and Turbo. The two runnable apps are:
apps/web – the official documentation / playground site. Entry point: apps/web/app/page.tsx. examples/dashboard – a minimal dashboard demo. Entry point: examples/dashboard/app/page.tsx.
Both apps import the shared packages (@json-render/core, @json-render/react) via workspace references, so any changes to the core library are reflected instantly.
How To Use It
Clone & install git clone https://github.com/your‑org/json-render.git cd json-render pnpm install # installs all workspace packages Configure – copy the example env files. cp apps/web/.env.example apps/web/.env cp examples/dashboard/.env.example examples/dashboard/.env
The only required variable is OPENAIAPIKEY (used by the /api/generate route). Run a demo – start the playground. pnpm dev --filter @json-render/web # runs Next.js in apps/web # or pnpm dev --filter @json-render/dashboard # runs the dashboard example
The scripts are defined in each app’s package.json ("dev": "next dev"). The server will be reachable at http://localhost:3000. Hook into your own app – import the library from the workspace:
// src/registry.ts import { Card, Metric, Button } from '@json-render/ui';
export const registry = { Card, Metric, Button, };
// src/Dashboard.tsx import { Renderer, useUIStream } from '@json-render/react'; import { registry } from './registry';
export default function Dashboard() { const { tree, send } = useUIStream({ api: '/api/generate' });
return ( <> <input onKeyDown={e => e.key === 'Enter' && send(e.currentTarget.value)} /> <Renderer tree={tree} components={registry} /> </> ); }
The useUIStream hook lives in packages/react/src/hooks.tsx and connects to the apps/web/app/api/generate/route.ts endpoint, which streams the model’s JSON response.
Real‑World Use
A SaaS platform could expose a “Create Dashboard” prompt. The backend calls OpenAI, streams the JSON to the client, and json-render renders the UI instantly, while the catalog guarantees that only approved widgets (e.g., Card, Metric, Button) appear. Actions such as exportreport are declared in the JSON and handled by the host via the ActionProvider (packages/react/src/contexts/actions.tsx).
<ActionProvider actions={{ exportreport: () => downloadPDF(), refreshdata: () => refetchMetrics(), }}> <Dashboard /> </ActionProvider>
Code Health & Issues
Low – Missing root start script – package.json at repo root has no "dev" or "build" script, requiring developers to know the --filter flag. Low – Limited test coverage for UI layer – Tests exist for core utilities (packages/core/src/.test.ts) but the React renderer only has a single test file (packages/react/src/renderer.test.tsx). UI edge cases may be under‑tested. Medium – Env variable exposure – .env.example mentions OPENAIAPI_KEY; the repo does not enforce secret management (e.g., via Vercel env UI), which could be a risk in CI if accidentally committed. Low – No explicit TypeScript strictness – tsconfig.json files exist, but the repo does not show "strict": true. Enabling strict mode would catch potential type mismatches early. None – License present – LICENSE file is included, satisfying open‑source compliance. None – CI configured – GitHub Actions workflow (.github/workflows/ci.yml) runs lint, typecheck, and tests on each PR, indicating a healthy CI pipeline.
The Bottom Line
json-render delivers a solid, type‑safe framework for turning LLM‑generated JSON into React UI while keeping the component surface area under strict control. The monorepo layout, existing examples, and CI make it ready for integration, though teams should add a top‑level start script and expand UI tests before production use. Ideal for organizations that need predictable AI‑generated dashboards or widgets and can operate within a Next.js/React stack.