콘텐츠 스키마 enum 누락으로 빌드 실패한 문제 수정

content.config.ts 에서 콘텐츠 스키마 enum 하나가 빠져 있었다.

배경

콘텐츠 컬렉션 기반으로 정적 콘텐츠를 관리하는 구조에서, category 필드는 enum 으로 허용 값을 명시적으로 제한하고 있었다. 그런데 region 카테고리로 작성된 마크다운 파일이 빌드 타임에 스키마 검증을 통과하지 못하는 문제가 있었다. 콘텐츠 자체는 이미 작성되어 있었고, 스키마만 뒤처진 상황.

이런 케이스가 생각보다 자주 발생하는데, 보통 두 가지 패턴으로 터진다.

• 콘텐츠 작성자(또는 본인)가 스키마 정의를 먼저 보지 않고 직관적으로 카테고리를 써 버리는 경우
• 기획 단에서 카테고리가 추가됐는데 스키마 반영이 누락된 채 콘텐츠가 먼저 올라오는 경우

이번엔 후자 쪽이었다. region 이라는 카테고리는 이미 콘텐츠 기획에서 확정된 값이었는데, content.config.ts 에 추가하는 작업이 빠진 채로 콘텐츠 파일이 먼저 머지됐다.

작업 내용

변경은 단순하다. src/content.config.ts 에서 category 필드의 enum 배열에 "region" 을 추가한 것.

// before
category: z.enum(["guide", "faq", "notice"]),

// after
category: z.enum(["guide", "faq", "notice", "region"]),

파일 하나, 수정 한 줄. 변경 stat 자체는 아주 작은 핀포인트 수정이지만, 이 한 줄이 없으면 region 카테고리로 작성된 콘텐츠 파일 전부가 빌드에서 튕겨나간다. 콘텐츠 컬렉션의 스키마 검증은 꽤 엄격하게 동작하기 때문에, enum 에 없는 값은 타입 에러가 아니라 빌드 실패로 이어진다.

회고

작은 수정이지만 짚고 싶은 게 있다. 스키마와 콘텐츠의 동기화 타이밍 문제다.

콘텐츠 컬렉션 구조를 팀에서 쓸 때, 스키마 정의(content.config.ts)는 일종의 계약서 역할을 한다. 콘텐츠 작성자가 지켜야 할 규칙을 코드로 명시한 것. 그런데 이 계약서가 콘텐츠보다 항상 먼저 업데이트된다는 보장이 없다. 특히 콘텐츠를 작성하는 주체와 스키마를 관리하는 주체가 분리되어 있거나, PR 이 따로 올라오는 상황에서는 이런 순서 역전이 자연스럽게 생긴다.

이걸 팀 차원에서 막으려면 몇 가지 선택지가 있다.

• 콘텐츠 PR 머지 전에 스키마 반영 여부를 체크리스트로 확인
• CI 에서 콘텐츠 파일의 카테고리 값과 스키마 enum 을 비교하는 lint 단계 추가
• 스키마 변경과 콘텐츠 추가를 같은 PR 에 묶는 컨벤션 도입

당장은 fix commit 으로 마무리했지만, 같은 패턴이 반복된다면 세 번째 옵션 정도는 팀 컨벤션으로 못 박아두는 게 맞다고 본다. 스키마 파일은 콘텐츠 추가 PR 에 항상 같이 올라와야 한다, 한 줄짜리 규칙이지만 이게 지켜지면 이런 류의 빌드 실패는 거의 사라진다.

단 한 줄 수정이 빌드를 살렸다. 근데 그 한 줄을 처음부터 같이 올렸어야 했다.

끝.

🛒 이 글과 어울리는 추천 상품

• 외장SSD 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 모니터암 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.