가이드 / 컬렉션
가이드 / collections
컬렉션
공개 범위, 필드, 카테고리, 권한 규칙, 훅.
수정 2026년 11월 20일편집 docs seed버전 1
컬렉션은 문서의 종류예요. 글, 가이드, 공지처럼요. 모든 컬렉션이 같은 테이블을 써서, 컬렉션을 더해도 마이그레이션이 필요 없어요.
옵션#
defineCollection({
slug: "posts",
label: "Blog",
visibility: "public", // 필수: "public" 또는 "internal"
categories: ["News", "Engineering"],
versions: { max: 100, drafts: true }, // 수정은 게시할 때까지 기다려요
search: { enabled: true },
fields: z.object({ cover: z.string().url().optional() }),
admin: { fields: { cover: { label: "Cover image" } } },
url: (d) => `/blog/${d.slug}`,
access: { write: ({ actor }) => actor.kind === "user" && actor.isAdmin },
});공개 범위#
컬렉션마다 public인지 internal인지 정해요. internal 컬렉션은 누가 읽을 수 있는지(access.read)를 꼭 정해야 해요. 정하지 않으면 CMS가 시작되지 않아서, 실수로 공개되는 일이 없어요.
필드#
fields는 zod 객체예요. 편집기는 이걸로 입력 폼을 만들고, cms.get은 fields를 zod 결과 타입으로 돌려줘요. update에서 fields는 JSON Merge Patch예요. 보낸 키는 바뀌고, null은 지우고, 나머지는 그대로예요.
권한#
기본값: 공개 컬렉션의 게시된 문서는 누구나 읽어요. 관리자는 쓰고 게시해요. API 키는 범위(read, write, publish, admin, 필요하면 컬렉션별)만큼 할 수 있어요. 컬렉션마다 read, write, publish를 바꿀 수 있어요.
managed: true면 앱 코드(system)만 쓸 수 있는 컬렉션이 돼요.
훅#
afterChange 훅과 cms.onChange는 두 번째 인자로 { contentChanged }를 받아요. 초안만 바뀌고 공개본이 그대로면 false라서, 그때는 페이지를 다시 만들지 않아도 돼요.
createCms의 timeZone(기본 UTC)은 사용 기록을 어느 날짜로 셀지 정해요.