Build & Ship an Airport Directory

Profound CMS에서 실제 국제화된 공항 디렉터리를 구축하세요: 하나의 URL 패턴으로 35개 언어로 모든 공항 페이지를 렌더링합니다. Next.js 코드를 작성하고 CMS 구조를 직접 구성하세요; Claude Code(Profound MCP를 통해)가 세 가지 작업을 처리합니다 — 공항 데이터를 생성하고, 디자인 시스템을 연결하며, 네 개의 React 컴포넌트를 생성합니다. 세 파트: Setup, Build, Production.

전체 비디오 워크스루 보기.

만들 결과물

• ~50개의 공항 레코드가 각자의 URL에 위치합니다.
• 하나의 매개변수 라우트 /{language}/{airport_code}.
• 네 개의 UI 요소 — nav, headline, body, footer — 가 cms-renderer에 의해 렌더링됩니다.
• CEL 바인딩을 통한 실시간 CMS 데이터.
• 한 번의 클릭으로 35개 언어 전체를 번역합니다.
• GitHub와 연결된 Vercel에 배포하여 라이브 프리뷰와 현장 편집을 제공합니다.

사전 준비 사항

• Bun ≥ 1.3 — curl -fsSL https://bun.sh/install | bash
• Profound MCP가 연결된 Claude Code(파트 1).
• Profound CMS 계정.
• 파트 3용: GitHub에 로그인된 GitHub CLI(gh)와 GitHub에 연결된 Vercel 계정.

구성 방식

• 컴포넌트는 콘텐츠 구조를 정의합니다. Route Slug 필드는 컴포넌트를 라우팅 가능하게 만들고, UI Element 태그는 페이지에 배치할 수 있게 하며, language 같은 시스템 컴포넌트는 기본으로 제공됩니다.
• Variant는 콘텐츠 자체입니다(JFK, SFO, LAX…).
• UI 요소는 페이지 섹션이며, 렌더 시 평가되는 Profound의 템플릿 내 스크립팅 CEL로 채워집니다.
• 매개변수 라우트는 URL을 하나의 Variant와 UI 요소 집합에 매핑합니다.
• Next.js 앱은 읽기 전용 API 키와 함께 cms-renderer SDK를 통해 모든 것을 렌더링합니다.

파트 1 — 설정

최종 상태: CMS에 ~50개의 공항이 있고, 앱이 이를 읽도록 연결되며, 디자인 시스템이 구성됩니다.

1. 웹사이트 생성

Profound(WorkOS 인증)에 가입하고 airports라는 웹사이트를 만듭니다. 두 가지를 복사하세요: website ID(관리자 URL의 UUID)와 Deployments → Create API key에서 발급받은 읽기 전용 API 키. 앱은 읽기만 하므로 읽기 키만 필요합니다.

2. 앱 스캐폴딩 및 연결

bunx create-profound-next airports
cd airports

자격 증명을 .env.local에 추가하세요:

PROFOUND_API_KEY=<your read key>
NEXT_PUBLIC_PROFOUND_WEBSITE_ID=<your website id>
NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_BUNNY_CDN_URL=https://cms-profound.b-cdn.net

bun dev를 실행하고 localhost:3000을 열어 연결을 확인합니다.

3. airport 컴포넌트 생성

관리자에서 Components → Create new component로 이동해 이름을 airport로 지정합니다. 여섯 개 필드를 추가하세요: code, name, city, country(Text)와 latitude, longitude(Number). code를 Route Slug 필드로 표시하고 상태를 Active로 설정합니다. 모든 필드는 선택 사항으로 두고, UI Element 태그는 추가하지 마세요.

airport 컴포넌트 — 여섯 개의 필드와 Route Slug로 설정된 code 필드.

4. 컴포넌트를 타입으로 가져오기

bun run generate-schemas

이 명령은 airportSchema(Zod)와 Airport(type)를 generated/cms-schemas.ts에 작성하며 자격 증명도 확인합니다.

5. MCP를 통해 데이터 시드하기

MCP를 연결하고 인증하세요:

claude mcp add --transport http Profound http://107.21.107.99:8081/mcp

서버는 OAuth(WorkOS)로 인증합니다. Claude Code에서 /mcp를 실행하고 Profound를 선택한 뒤 브라우저에서 로그인을 완료하세요 — Profound 도구를 처음 호출하면 Claude Code가 자동으로 프롬프트를 띄웁니다. /mcp에 Profound가 connected로 표시되면 Claude에게 다음과 같이 요청하세요:

실제 공항 50곳을 생성하세요 — 올바른 IATA 코드, 이름, 도시, 국가, 좌표를 포함합니다. 이를 data 폴더의 JSON으로 저장하고, 우리 airport 컴포넌트에 대해 검증한 뒤, Profound MCP를 통해 병렬로 게시된 문서로 각각 생성하세요.

airport → Variants를 열어 ~50개의 게시된 공항을 확인합니다. 앱은 API 키로 읽고, MCP는 자체 WorkOS 세션으로 기록합니다.

약 50개의 공항이 게시된 Variant로 시드되었습니다.

6. 디자인 시스템 추가

스캐폴드는 스타일이 없습니다. 프로젝트 루트에 DESIGN.md(Tailwind v4 @theme 블록과 토큰)를 두세요 — 직접 작성하거나 refero.design에서 다운로드해도 됩니다. 그런 다음 Claude에게 요청하세요:

DESIGN.md를 읽고 Tailwind v4를 설정한 뒤 테마와 폰트를 연결하세요. 폰트는 런타임 Google import가 아니라 next/font를 사용하세요. 스타일링만 — 페이지나 컴포넌트는 아직 만들지 마세요.

src/app/globals.css에 @import "tailwindcss";와 @theme 블록이 포함되어 있는지, localhost:3000에서 토큰이 표시되는지 확인하세요.

파트 2 — 빌드

렌더링 레이어를 구축합니다: UI 요소, React 컴포넌트, 라우트, CEL 바인딩, 번역을 설정합니다.

1. 네 개의 UI 요소 컴포넌트 정의

관리자에서 Create new component를 네 번 실행합니다(Route Slug 없음). 각 컴포넌트마다 필드를 Text로 추가하고(명시된 경우 제외), 상태를 Active로 설정한 뒤 Settings → Tags에서 UI Element 태그를 추가하세요:

• nav → brand
• headline → title, subtitle
• body → code, city, country, latitude(Number), longitude(Number)
• footer → text

body.latitude와 body.longitude는 공항 컴포넌트와 일치하도록 반드시 Number여야 합니다.

각 UI 요소는 자체 컴포넌트입니다 — 여기서는 body가 Active로 설정되고 UI Element 태그가 추가되어 있습니다.

모든 UI 요소가 airport 컴포넌트와 함께 나열되어 있습니다.

2. 타입 다시 생성

bun run generate-schemas

3. React 컴포넌트 생성 및 등록

Claude에게 다음과 같이 요청하세요:

components/에 nav, headline, body, footer라는 네 개의 React 컴포넌트를 생성하세요. 각 컴포넌트는 생성된 타입 T를 사용하는 BlockComponentProps<T> 타입의 단일 content prop을 받아 content에서 필드를 읽어야 합니다. 네 컴포넌트를 catch-all 라우트의 레지스트리에 컴포넌트 이름으로 등록하세요. 디자인 시스템으로 스타일링하되, 우리만의 컴포넌트로 구현하고 소스 사이트 레이아웃을 복사하지 마세요. Nav: 왼쪽에 브랜드. Headline: code · city, country 서브타이틀을 가진 공항 이름. Body: 코드, 도시, 국가, 좌표가 포함된 상세 패널. Footer: 고정된 한 줄 텍스트. 레이아웃과 스타일링만 처리하세요.

Claude는 네 개의 컴포넌트를 생성하고 src/app/[...slug]/page.tsx의 레지스트리에 채웁니다:

const registry = { nav: Nav, headline: Headline, body: Body, footer: Footer };

규칙 두 가지: 각 컴포넌트는 필드를 content에서 읽어야 하며(개별 prop 금지), 레지스트리 키는 CMS 컴포넌트 이름과 정확히 일치해야 합니다 — 일치하지 않으면 렌더링되지 않습니다.

4. 매개변수 라우트 생성

관리자에서 Pages → Create page로 이동해 패턴을 /{airport_code}로 설정합니다. Dynamic Segment Mappings에서 airport_code를 airport 컴포넌트의 slug 필드 code에 매핑합니다. 저장하면 Page Builder로 이동합니다. /JFK가 해석되는지 확인하세요.

5. UI 요소 추가, CEL 연결, 게시

Custom 탭에서 UI 요소를 페이지에 추가합니다.

JFK 바인딩의 Page Builder에 네 개의 UI 요소가 추가된 상태입니다.

1. JFK 바인딩을 선택하고 Add UI Element → Custom 탭 → nav, headline, body, footer 순서로 추가하세요. Profound는 이 구성을 모든 공항 바인딩으로 전파합니다.

2. 각 필드를 채웁니다. 정적 값(nav 브랜드, footer 텍스트)은 직접 입력하세요. 동적 값은 동적으로 전환한 뒤 CEL을 작성하세요. 공유 조회는 documents.get("airport", meta.params.airport_code)입니다.

   필드	CEL 값
   headline.title	documents.get("airport", meta.params.airport_code).name
   headline.subtitle	documents.get("airport", meta.params.airport_code).code + " · " + documents.get("airport", meta.params.airport_code).city + ", " + documents.get("airport", meta.params.airport_code).country
   body.code / body.city / body.country	documents.get("airport", meta.params.airport_code).<field>
   body.latitude / body.longitude	documents.get("airport", meta.params.airport_code).latitude 및 .longitude
   nav.brand, footer.text	정적 문자열

3. 페이지를 Publish(우측 상단)하세요.

6. 영어로 확인

localhost:3000/JFK를 연 다음 /SFO, /LAX도 열어보세요 — 동일한 템플릿에 다른 공항이 적용됩니다.

완성된 페이지가 JFK 데이터를 영어로 렌더링합니다.

7. 국제화

1. 먼저 컴포넌트를 번역하세요. 관리자에서 각 컴포넌트(필수로 UI 요소일 필요는 없음)를 열고 Translate → Submit을 클릭하세요. Profound는 한 번에 35개 언어로 콘텐츠를 번역하며, 정적 필드 값도 포함됩니다. 라우트를 수정하거나 CEL을 건드리기 전에 이 작업을 수행하세요.

   

   Translate → Submit은 한 번에 35개 언어로 컴포넌트를 전송합니다.

2. 언어 차원을 추가하세요. Pages에서 패턴을 /{language}/{airport_code}로 변경합니다. language에 대한 Dynamic Segment Mapping을 추가하고 내장 language 시스템 컴포넌트의 slug 필드를 code로 설정하세요. 저장 후 /en/JFK가 해석되는지 확인합니다.

   

   {language} 세그먼트를 라우트에 추가하는 모습입니다.

3. 모든 번역 가능한 필드를 번역된 fetch로 연결하세요. 페이지를 국제화하려면 언어에 따라 달라지는 모든 필드를 documents.get(...)에서 documents.translated("airport", meta.params.airport_code, meta.params.language)로 전환해야 합니다:

   필드	번역된 CEL
   headline.title	documents.translated("airport", meta.params.airport_code, meta.params.language).name
   headline.subtitle	documents.get("airport", meta.params.airport_code).code + " · " + documents.translated("airport", meta.params.airport_code, meta.params.language).city + ", " + documents.translated("airport", meta.params.airport_code, meta.params.language).country
   body.city / body.country	documents.translated("airport", meta.params.airport_code, meta.params.language).city 및 .country

   IATA code와 좌표는 언어와 상관없이 동일하므로 documents.get을 그대로 사용합니다. nav.brand와 footer.text는 이미 1단계에서 번역되었습니다.

세 가지가 모두 완료되면 /fr/SFO, /de/SFO 등 모든 언어가 완전히 번역되어 표시됩니다.

파트 3 — 프로덕션

1. 배포: GitHub, 그리고 Vercel

GitHub에 푸시하세요:

git init
git add -A
git commit -m "Airport directory"
gh repo create airports --public --source=. --push

Vercel에 가져오기: Add New → Project → airports 저장소를 가져옵니다. 환경 변수를 추가하세요 — PROFOUND_API_KEY, NEXT_PUBLIC_PROFOUND_WEBSITE_ID, NEXT_PUBLIC_CMS_API_URL, 필요하면 NEXT_PUBLIC_BUNNY_CDN_URL — 그다음 Deploy를 클릭합니다. /en/JFK와 /fr/SFO를 방문하세요. 이후 git push마다 자동 배포됩니다.

2. 라이브 프리뷰와 현장 편집

두 기능 모두 스캐폴드에 포함되어 있습니다.

• 라이브 프리뷰: layout.tsx의 <Refresher>는 관리자가 편집 후 저장할 때, 미리보기 중인 페이지를 재배포 없이 업데이트합니다.
• 현장 편집: 어떤 URL에든 ?edit_mode=true를 추가하세요(예: …/en/JFK?edit_mode=true). 그러면 편집 오버레이가 표시됩니다. 일반 방문자는 깨끗한 페이지를 그대로 보게 됩니다.

?edit_mode=true는 라이브 페이지 위에 편집기를 오버레이합니다.

이것이 빌드 과정입니다

50개의 공항, 35개 언어, 실시간 — 한 번 설계하고 데이터를 채워 넣습니다: 하나의 라우트, 네 개의 React 컴포넌트, 몇 개의 CEL 바인딩. CMS가 콘텐츠를 보관하고, 여러분의 코드가 이를 렌더링하며, CEL이 둘을 연결합니다.