시작하기
1. API 키 발급
- 어드민(
mysite.roottale.com) 로그인 - 설정 > 사이트 연결 키 메뉴로 이동
- 새 키 발급 — 권한 선택:
- read (기본): 발행된 콘텐츠 조회만. 외부 사이트 연동은 이걸로 충분
- read_write: 쓰기 포함 (자동화 서버용 — 일반 연동에는 불필요)
- 발급된 키(
rtlk_cust_+ 24자)는 발급 직후 1회만 평문 표시됩니다. 바로 복사해 환경변수에 저장하세요.
키는 사이트 단위로 스코프되어(site-scoped) 해당 사이트의 콘텐츠·웹훅 검증에만 사용됩니다.
2. 환경변수
# .env.local (Next.js) 또는 배포 플랫폼의 환경변수 — 반드시 서버 전용
ROOTTALE_API_KEY=rtlk_cust_xxxxxxxxxxxxxxxxxxxxxxxx
# (선택) API 베이스 오버라이드 — 기본값 https://api.roottale.com 이면 생략
# ROOTTALE_API_BASE=https://api.roottale.com
# 사이트 정식 도메인 (RSS/sitemap/canonical 생성용)
NEXT_PUBLIC_SITE_URL=https://example.com
중요: ROOTTALE_API_KEY는 절대 NEXT_PUBLIC_* 접두를 붙이지 마세요.
브라우저로 노출되면 누구나 그 키로 API를 호출할 수 있습니다.
@roottale/cms-client는 브라우저에서 실행되면 의도적으로 에러를 던집니다.
3. 패키지 설치
# Next.js 사이트
npm install @roottale/cms-client @roottale/cms-renderer-next
# 또는
pnpm add @roottale/cms-client @roottale/cms-renderer-next
요구사항: Node ≥ 18.18, React 19, Next.js 14+ (renderer-next 사용 시).
렌더러 스타일은 root layout에서 1회 import:
// app/layout.tsx
import "@roottale/cms-renderer-next/styles";
예시 코드는 @/lib/blog 형태의 import를 사용합니다 — create-next-app 기본
설정이면 그대로 동작하고, tsconfig를 직접 구성했다면 paths alias가 필요합니다:
// tsconfig.json > compilerOptions
"paths": { "@/*": ["./*"] } // 또는 ["./src/*"]
4. 첫 조회 — 동작 확인
// 서버 컴포넌트, Route Handler, 또는 빌드 스크립트에서
import { fetchPosts } from "@roottale/cms-client/server";
const page = await fetchPosts({
apiKey: process.env.ROOTTALE_API_KEY!,
limit: 5,
type: "post",
});
console.log(page.items.map((p) => p.slug));
응답이 비어 있다면 어드민에서 글이 발행(published) 상태인지 확인하세요. 공개 API는 발행된 콘텐츠만 반환합니다.
401 에러(invalid_key)면 키 값/환경변수 로딩을 확인하세요.
다음 단계
- 블로그 페이지 구현 →
blog.md - 발행 즉시 사이트 반영 →
revalidation-webhooks.md