분산된 선언 구조의 통합을 통한 Page Builder의 Silent Bug 제거

Every Sanity page builder has the same bug

Maciej Trzciński 🌱🇵🇱2026년 6월 29일6분intermediate

AI 요약

Context

Sanity와 Next.js 기반의 Page Builder 구현 시 Schema, GROQ query, Component, Renderer map, Type 정의가 5개 지점으로 분산된 구조의 한계 분석. 이로 인해 특정 설정 누락 시 에러 없이 화면이 공백으로 출력되는 Silent Failure가 반복적으로 발생하는 문제 발생.

Technical Solution

Co-location 패턴 도입을 통한 Section 타입, Query, Renderer를 단일 객체로 정의하여 선언적 일관성 확보
createPageBuilderFromSections 팩토리를 통한 개별 Section 정의 기반의 통합 GROQ Projection 자동 생성
TypeScript Mapped Type을 활용하여 Block Union 타입과 Renderer Map 간의 1:1 대응 관계를 컴파일 타임에 강제
strict: true 옵션을 통한 미등록 Section 렌더링 시 Silent Skip 대신 명시적 Exception 발생 구조 설계
assertPageBuilderIntegrity 테스트 함수 도입으로 Runtime GROQ와 Schema, Renderer 간의 정합성을 CI 단계에서 검증
Convention-based Preview 시스템 구축으로 파일명 기반 썸네일 자동 매핑 및 Studio 설정 코드 제거

실천 포인트

1. 설정 정보가 3곳 이상으로 분산되어 동일한 변경 사항을 반복 입력하고 있는지 검토

2. 런타임에 조용히 실패하는 'Silent Failure' 지점을 찾아 명시적 Exception 발생 구조로 변경

3. 수동으로 관리하는 매핑 테이블을 TypeScript Mapped Type으로 대체하여 타입 안전성 확보

4. 설정 파일과 실제 구현체 간의 정합성을 검증하는 자동화 테스트(Integrity Test) 추가

태그

#Co-location #Mapped Types #Silent Failure #Groq #Single Source of Truth

원문 읽기