json-render 딥다이브
— AI가 만드는 UI를, "안전한 JSON"으로 가두는 프레임워크

1프로젝트 한줄 요약

이 레포가 정확히 무엇을 하는 물건인가.

즉 흐름은 ① 프롬프트 → ② AI + 카탈로그 → ③ JSON spec → ④ 렌더러의 4단계다. AI의 출력은 "코드"가 아니라 데이터(JSON)이기 때문에, 검증(validate)·스트리밍·재현이 가능하고, React Native·PDF·이메일·3D·터미널 등 같은 JSON을 여러 플랫폼에서 재사용할 수 있다.

// AI가 생성하는 것은 코드가 아니라 이런 "평면 spec" JSON
{
  "root": "card-1",
  "elements": {
    "card-1": { "type": "Card", "props": { "title": "안녕" }, "children": ["btn-1"] },
    "btn-1":  { "type": "Button", "props": { "label": "클릭" }, "children": [] }
  }
}

2왜 주목받는가

왜 Vercel Labs가 이걸 내고, 트렌딩에 올랐는가.

2024~2025년 "AI가 만드는 UI"는 큰 화두였다. Vercel의 AI SDK에는 이미 generative UI(툴 호출로 React 컴포넌트를 스트리밍) 기능이 있었지만, 그건 개발자가 코드로 컴포넌트를 미리 짜 두고 AI가 그중 하나를 고르는 방식에 가까웠다. json-render는 한 발 더 나아가 AI 출력 자체를 검증 가능한 데이터 명세로 표준화하고, 그 명세를 거의 모든 렌더 타깃으로 확장했다. 트렌딩 이유를 셋으로 정리한다.

3기술 스택 전체 지도

코어 / 렌더러 / 상태·도구 / 빌드·인프라로 나눠 본다.

json-render는 pnpm + Turborepo 모노레포다. 30개가 넘는 npm 패키지(@json-render/*)가 한 저장소에 들어 있고, 모두 @json-render/core 위에 얹힌다. 핵심은 "코어는 프레임워크를 모른다"는 점 — core는 순수 TypeScript + zod로 스키마·검증·스트리밍만 담당하고, React/Vue/Svelte 의존성은 각 렌더러 패키지가 가진다.

① 코어 (프레임워크 무관 두뇌)

② 렌더러 (타깃별 출력)

③ 상태·도구·연동

④ 빌드·인프라

4아키텍처 심화 분석

프롬프트가 화면이 되기까지, 그리고 핵심 설계 패턴.

전체 파이프라인은 단순하지만 각 단계가 명확히 분리돼 있다. 아래 그림은 "사용자 입력 → LLM → JSON spec → 렌더러 → 화면"의 흐름과, 그 안에서 가드레일·스트리밍·상태가 어디서 작동하는지를 보여준다.

핵심 설계 패턴 4가지

{
  "type": "Pressable",
  "props": {
    "action": "setState",
    "actionParams": { "statePath": "/activeTab", "value": "home" }
  }
}
// 다른 노드: 상태 값에 따라 아이콘이 자동으로 바뀜
{
  "type": "Icon",
  "props": {
    "name": { "$cond": { "$state": "/activeTab", "eq": "home" },
              "$then": "home", "$else": "home-outline" }
  }
}

5디렉토리 구조 해부

모노레포의 어디에 무엇이 있는가.

루트는 pnpm 워크스페이스 설정과 Turborepo 파이프라인이고, 실제 코드는 packages/(라이브러리), apps/web(문서 사이트), examples/(데모), skills/(AI 에이전트용 사용법)로 나뉜다.

6학습 포인트 (기술별)

이 레포를 뜯어보며 실제로 손에 남기면 좋은 것들.

Zod로 "스키마 = 진실원" 설계하기

core의 카탈로그는 zod 스키마로 컴포넌트 props를 정의하고, 그 스키마에서 ① 타입(개발자용) ② 런타임 검증 ③ LLM 프롬프트(JSON Schema 설명) 세 가지를 동시에 뽑아낸다. "한 번 정의, 세 곳에서 활용"하는 설계는 어떤 데이터 중심 앱에서도 강력한 패턴이다.

// 카탈로그: props 스키마 + 설명이 곧 AI에게 주는 명세
const catalog = defineCatalog(schema, {
  components: {
    Metric: {
      props: z.object({
        label: z.string(),
        value: z.string(),
        format: z.enum(["currency","percent","number"]).nullable(),
      }),
      description: "지표 값 하나를 표시",   // ← LLM이 읽는 힌트
    },
  },
  actions: { refresh_data: { description: "모든 지표 새로고침" } },
});
const systemPrompt = catalog.prompt();   // 프롬프트 자동 생성

스트리밍 파서 — 불완전한 JSON 다루기

LLM이 토큰을 흘리는 중간에는 JSON이 닫히지 않은 "부서진" 상태다. createSpecStreamCompiler는 이런 부분 청크를 받아 지금까지 만들어진 만큼의 spec을 돌려준다. 스트리밍 LLM UI를 만들 때 핵심이 되는 기술 — 직접 구현하면 까다로운 부분을 라이브러리가 해결한 사례를 코드로 배울 수 있다.

const compiler = createSpecStreamCompiler();
for await (const chunk of stream) {
  const { result, newPatches } = compiler.push(chunk);
  setSpec(result);              // 부분 결과로 즉시 화면 갱신
}
const finalSpec = compiler.getResult();

의존성 역전 & 어댑터 패턴

@json-render/core는 React/Vue를 전혀 모른다. 대신 StateStore·렌더러 같은 인터페이스만 정의하고, 구체 구현은 바깥(react·zustand 패키지)에서 주입한다. 라이브러리를 프레임워크에 묶이지 않게 설계하는 정석을 실물로 볼 수 있다.

AI SDK 연동 (실전 코드)

examples/chat의 API 라우트는 Vercel AI SDK의 스트림을 pipeJsonRender로 감싸 클라이언트에 보낸다. AI Gateway에 모델을 문자열 ID("anthropic/claude-haiku-4.5")로 넘기는 최신 패턴도 함께 익힌다.

// app/api/generate/route.ts (요지)
const result = await agent.stream({ messages: modelMessages });
const stream = createUIMessageStream({
  execute: async ({ writer }) => {
    writer.merge(pipeJsonRender(result.toUIMessageStream()));
  },
});
return createUIMessageStreamResponse({ stream });

7시스템 요구사항

개발·실행에 필요한 환경.

라이브러리 자체는 가볍지만, 모노레포 전체를 빌드하려면 비교적 최신 툴체인이 필요하다. 루트 package.json의 engines가 이를 강제한다(engineStrict: true).

단지 라이브러리를 쓰기만 할 거라면 요구사항은 훨씬 낮다 — 일반적인 React/Vue 프로젝트에 npm install @json-render/core @json-render/react로 추가하면 끝이다. peerDependency로 zod와 해당 프레임워크가 필요하다.

8직접 해볼 수 있는 실습 과제

"읽기"에서 "만들기"로 — 난이도별 5단계.

9관련 기술 심화 학습 로드맵

json-render를 제대로 활용하기 위한 4주 코스.

10핵심 키워드 사전

코드를 읽다 막히는 용어 빠른 참조.

11참고 링크

• GitHub: vercel-labs/json-render
• 공식 사이트/문서: json-render.dev
• 핵심 패키지: @json-render/core · @json-render/react
• Vercel AI SDK: sdk.vercel.ai (Generative UI · streaming)
• Zod: zod.dev · Turborepo: turbo.build
• shadcn/ui: ui.shadcn.com (사전 제작 컴포넌트의 출처)
• MCP: modelcontextprotocol.io