개요
json-render는 AI가 자연어 프롬프트에 따라 인터페이스를 생성하도록 하는 생성형 UI 프레임워크이며, 사전에 정의한 컴포넌트만 사용할 수 있습니다. 출력되는 JSON은 항상 정의한 schema를 준수하므로 안전하고 신뢰할 수 있으며, 스트리밍 렌더링을 지원합니다. React, Vue, Svelte, React Native, 3D, 비디오, PDF, 이메일 및 터미널 등 다양한 플랫폼용 렌더러를 제공합니다.
README 미리보기
# json-render\n\n**The Generative UI framework.**\n\nGenerate dynamic, personalized UIs from prompts without sacrificing reliability. Predefined components and actions for safe, predictable output.\n\n\n \n \n \n \n\n\n```bash\n# for React\nnpm install @json-render/core @json-render/react\n# for React with pre-built shadcn/ui components\nnpm install @json-render/shadcn\n# or for React Native\nnpm install @json-render/core @json-render/react-native\n# or for video\nnpm install @json-render/core @json-render/remotion\n# or for PDF documents\nnpm install @json-render/core @json-render/react-pdf\n# or for HTML email\nnpm install @json-render/core @json-render/react-email @react-email/components @react-email/render\n# or for Vue\nnpm install @json-render/core @json-render/vue\n# or for Svelte\nnpm install @json-render/core @json-render/svelte\n# or for SolidJS\nnpm install @json-render/core @json-render/solid\n# or for terminal UIs\nnpm install @json-render/core @json-render/ink ink react\n# or for full Next.js apps (routes, layouts, SSR, metadata)\nnpm install @json-render/core @json-render/react @json-render/next\n# or for 3D scenes (and gaussian splatting via the GaussianSplat component)\nnpm install @json-render/core @json-render/react-three-fiber @react-three/fiber @react-three/drei three\n```\n\n## Why json-render?\n\njson-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:\n\n- **Guardrailed** - AI can only use components in your catalog\n- **Predictable** - JSON output matches your schema, every time\n- **Fast** - Stream and render progressively as the model responds\n- **Cross-Platform** - React, Vue, Svelte, Solid (web), React Native (mobile) from the same catalog\n- **Batteries Included** - 36 pre-built shadcn/ui components ready to use\n\n## Quick Start\n\n### 1. Define Your Catalog\n\n```typescript\nimport { defineCatalog } FAQ (5)
문제 해결Zod 4.4로 업그레이드한 후 @json-render에서 발생하는 "Invalid input: expected nonoptional, received undefined" visible 필드 오류를 해결하는 방법
이것은 @json-render (≤0.19.0)의 Zod 4.4 호환성 버그로, 요소의 선택적 visible 필드가 catalog.validate() 실행 중 필수 항목으로 잘못 처리되는 문제입니다. 해결 방법: 모든 @json-render 패키지(core, react, shadcn, react-email)를 v0.20.0 이상으로 업그레이드하세요. 수정 사항은 PR #299에 반영되었으며, zod 4.6을 사용하는 v0.21.1에서 정상 작동이 확인되었습니다. 즉시 업그레이드할 수 없는 경우에는 임시 해결 방법으로 zod를 4.3.6으로 고정하세요(pnpm add zod@4.3.6). zod 4.4.x 버전은 모두 이 오류를 유발하기 때문입니다.
문제 해결@json-render/solid에서 useBoundProp를 사용할 때 발생하는 'value is not a function' 오류를 해결하는 방법
README 예제가 잘못되었습니다: useBoundProp(propsValue, binding)은 [T | undefined, (value: T) => void] 튜플을 반환하며, 첫 번째 요소는 Solid accessor가 아닌 원시 prop 값입니다. 이를 value()처럼 호출하지 마세요. 올바른 사용법:
Input: (ctx) => {
const [value, setValue] = useBoundProp(ctx.props.value, ctx.bindings?.value);
return (
<input
value={String(value ?? "")}
onInput={(event) => setValue(event.currentTarget.value)}
/>
);
}Solid가 반응형 읽기를 추적할 수 있도록 JSX 내부에서 해석된 값을 직접 읽고, 업데이트에는 setter(setValue)를 사용하세요. 문서 예제는 PR #401(#381과 함께)에서 수정되었으며, 초기값, 외부 상태 업데이트, null 값을 다룹니다.
문제 해결@json-render/solid defineRegistry 콜백에서 'Cannot read properties of undefined (reading props)' 오류가 발생하는 이유는 무엇인가요?
defineRegistry() 콜백 컨텍스트에는 element 필드가 없습니다. 이전 README 예제에서는 renderProps.element.props를 잘못 사용했습니다. 콜백은 해석된 props를 ctx.props를 통해 직접 전달받습니다(children, emit, on, bindings, loading과 함께). 컴포넌트 콜백이 컨텍스트 루트에서 props를 읽도록 수정하세요:
const { registry } = defineRegistry(catalog, {
components: {
Card: (ctx) => (
<div class="card">
<h3>{ctx.props.title as string}</h3>
{ctx.children}
</div>
),
},
});참고: 하위 수준의 ComponentRenderer 계약만 element를 노출하며, defineRegistry() 어댑터는 노출하지 않습니다. README 예제는 PR #401에서 해석된 컨텍스트를 사용하고, 입력 값을 반응형으로 유지하며, 렌더러에 필요한 프로바이더를 포함하도록 수정되었습니다.
문제 해결json-render에서 'setValue does not exist on useFieldValidation' 오류를 해결하는 방법
useFieldValidation은 유효성 검사만 처리하며(errors와 validate를 반환) value나 setValue는 제공하지 않습니다. 이 값들은 대신 useBoundProp 훅에서 가져오세요. 올바른 사용법은 다음과 같습니다:
import { useBoundProp, useFieldValidation } from '@json-render/react';
function TextField({ element }) {
const [value, setValue] = useBoundProp(element.props.valuePath);
const { errors, validate } = useFieldValidation(
element.props.valuePath,
element.props.checks
);
return (
<div>
<label>{element.props.label}</label>
<input
value={value || ''}
onChange={(e) => setValue(e.target.value)}
onBlur={() => validate()}
/>
{errors.map((error, i) => (
<p key={i} className="text-red-500 text-sm">{error}</p>
))}
</div>
);
}이는 issue #107에서 수정된 문서 오류였습니다. useBoundProp의 setValue 없이 데이터를 직접 설정하면 바인딩 계층을 우회하게 되며, 이것이 유효성 검사가 올바르게 트리거되지 않았던 이유입니다.
문제 해결json-render action params에서 $item이 실제 값 대신 "list/0/url" 같은 경로 문자열을 반환하는 이유는 무엇인가요?
json-render 0.19.0 (React)에서 반복 요소(/list에 대한 repeat) 내의 action.params 안에 { "$item": "url" }을 사용하면 필드의 실제 값 대신 JSON 경로 문자열(예: "list/0/url")로 잘못 해석됩니다. **우회 방법:** action params에서 $item을 $bindItem으로 교체하세요: "params": { "url": { "$bindItem": "url" } } — 이렇게 하면 실제 필드 값이 올바르게 반환됩니다.