Build & Ship an Airport Directory

Създайте реална, интернационализирана директория на летища в Profound CMS: един URL шаблон, който визуализира страница за всяко летище на 35 езика. Вие пишете кода на Next.js и изграждате ръчно структурата в CMS; Claude Code (през Profound MCP) се грижи за три задачи — генериране на данните за летищата, свързване на дизайн система и генериране на четирите React компонента. Три части: Настройка, Изграждане, Продукция.

Гледайте пълното видео ръководство.

Какво ще изградите

• ~50 записа за летища, всеки на собствен URL.
• Един параметричен маршрут /{language}/{airport_code}.
• Четири UI елемента — навигация, заглавие, основна част, футър — визуализирани чрез cms-renderer.
• Живи CMS данни чрез привързвания CEL.
• Всички 35 езика, преведени с едно щракване.
• Деплойнато във Vercel с жив преглед и редактиране на място.

Предварителни изисквания

• Bun ≥ 1.3 — curl -fsSL https://bun.sh/install | bash
• Claude Code с включен Profound MCP (Част 1).
• Акаунт в Profound CMS.
• За Част 3: GitHub CLI (gh), вписан, и акаунт във Vercel, свързан с GitHub.

Как се свързва всичко

• Components определят формата на съдържанието. Поле Route Slug прави компонента достъпен чрез маршрут; етикет UI Element позволява поставянето му на страница; System компонентите (като language) идват вградено.
• Variants са съдържанието (JFK, SFO, LAX…).
• UI elements са секциите на страницата, попълнени с CEL — вграденото в шаблона скриптиране на Profound, което се изпълнява при рендериране.
• Параметричен маршрут картографира URL към вариант плюс набор от UI елементи.
• Вашето Next.js приложение визуализира всичко чрез SDK-то cms-renderer с API ключ за четене.

Част 1 — Настройка

Краен резултат: ~50 летища в CMS, приложението свързано да ги чете и дизайн системата интегрирана.

1. Създайте уебсайта

Регистрирайте се в Profound (WorkOS удостоверяване) и създайте уебсайт с име airports. Копирайте две неща: ID на уебсайта (UUID в URL адреса на админа) и API ключ за ниво четене от Deployments → Create API key. Приложението само чете, така че ключ за четене е достатъчен.

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 — шест полета, като code е зададено като Route Slug.

4. Вкарайте компонента в типовете

bun run generate-schemas

Това записва airportSchema (Zod) и Airport (тип) в 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 и завършете вписването в браузъра — Claude Code също ви подканя автоматично при първото извикване на инструмент на Profound. След като /mcp показва Profound като connected, дайте инструкция на Claude:

Генерирай петдесет реални летища — коректни IATA кодове, имена, градове, държави и координати. Запази ги като JSON в папка data, валидирай спрямо нашия компонент airport, после създай всеки като публикуван документ чрез Profound MCP, паралелно.

Отворете airport → Variants, за да потвърдите ~50 публикувани летища. Приложението чете с API ключа; MCP записва със собствената си WorkOS сесия.

Около 50 летища, заредени като публикувани варианти.

6. Добавете дизайн система

Генерираният проект идва без стилове. Поставете DESIGN.md (блок @theme на Tailwind v4 плюс токени) в основната директория — ваш собствен или изтеглен от refero.design. След това дайте инструкция на Claude:

Прочети DESIGN.md. Настрой Tailwind v4 и свържи темата и шрифтовете. Използвай next/font за шрифтовете, не динамичен Google импорт. Само стилизиране — без страници или компоненти.

Потвърдете, че src/app/globals.css съдържа @import "tailwindcss"; плюс блока @theme, и че localhost:3000 показва токените.

Част 2 — Изграждане

Изградете слоя за рендериране: UI елементите, React компонентите, маршрута, CEL вързванията и превода.

1. Дефинирайте четирите компонента за UI елементи

В администрацията изберете Create new component четири пъти (без Route Slug). За всеки добавете полетата като Text, освен ако е отбелязано, задайте статуса на Active и добавете етикета UI Element в Settings → Tags:

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

body.latitude и body.longitude трябва да са Number, за да съвпадат с компонента airport.

Всеки UI елемент е отделен компонент — тук body, зададен като Active с етикета UI Element.

Всички четири UI елемента заедно с компонента airport.

2. Генерирайте типовете отново

bun run generate-schemas

3. Генерирайте React компонентите и ги регистрирайте

Дайте инструкция на Claude:

Изгради четири React компонента — nav, headline, body, footer — в components/. Всеки приема един проп content, типизиран като BlockComponentProps<T> от cms-renderer/lib/types, където T е генерираният тип на елемента, и чете полетата от content. Регистрирай и четирите в регистъра на маршрута за всички сегменти по име на компонента. Стил с нашата дизайн система, но като собствени компоненти — не копирай оформлението на изходния сайт. Nav: брандът вляво. Headline: име на летището с подзаглавие code · city, country. Body: панел с детайли за code, city, country и координати. Footer: един статичен ред. Само оформление и стил.

Claude създава четирите компонента и попълва регистъра в src/app/[...slug]/page.tsx:

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

Две правила: всеки компонент чете полетата от content (не като отделни пропове), а ключовете в регистъра трябва да съвпадат точно с имената на компонентите в CMS — несъответствие води до празен рендер.

4. Създайте параметричния маршрут

В администрацията отидете на Pages → Create page и задайте шаблона /{airport_code}. В Dynamic Segment Mappings свържете airport_code → компонента airport, поле slug code. Запишете — ще попаднете в Page Builder. Проверете, че /JFK се зарежда.

5. Добавете UI елементите, свържете CEL и публикувайте

Добавяне на UI елемент към страницата от таба Custom.

Четирите UI елемента, добавени към обвързването за JFK в Page Builder.

1. Изберете обвързването JFK → Add UI Element → таб Custom → добавете nav, headline, body, footer в този ред. Profound разпространява набора към всяко обвързване на летище.

2. Попълнете всяко поле. Статични стойности (бранд на навигацията, текст на футъра): въведете директно. Динамични стойности: преминете на динамичен режим и напишете CEL. Споделеният lookup е 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. Публикувайте страницата (горе вдясно).

6. Проверете на английски

Отворете localhost:3000/JFK, после /SFO, /LAX — един и същ шаблон, различни летища.

Готовата страница с данните за JFK, на английски.

7. Интернационализирайте

1. Първо преведете компонентите. В администрацията отворете всеки компонент (който и да е — не е нужно да е UI елемент) и щракнете Translate → Submit. Profound превежда съдържанието му на всички 35 езика наведнъж, включително статичните полета. Направете това преди да редактирате маршрута или CEL.

   

   Translate → Submit изпраща компонент към всички 35 езика наведнъж.

2. Добавете измерението за език. В Pages променете шаблона на /{language}/{airport_code}. Добавете Dynamic Segment Mapping за language → вградения системен компонент language, поле slug code. Запишете и проверете, че /en/JFK се зарежда.

   

   Добавяне на сегмента {language} към маршрута.

3. Насочете всяко преводимо поле към преведеното извличане. Интернационализирането на страницата означава да смените всяко езиково зависимо поле — не само заглавието — от 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 вече са покрити чрез Translate в стъпка 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. Жив преглед и редакция на място

И двете са налични в шаблона.

• Live preview: <Refresher> в layout.tsx обновява страницата, която преглеждате, когато редактирате и записвате в админа — без нов деплой.
• Редакция на място: добавете ?edit_mode=true към всеки URL (например …/en/JFK?edit_mode=true), за да получите наслагвания за редакция. Публичните посетители все още виждат чистата страница.

?edit_mode=true наслагва редактора върху живата страница.

Това е проектът

Петдесет летища, 35 езика, на живо — описано веднъж и запълвано с данни: един маршрут, четири React компонента и няколко CEL вързвания. CMS съхранява съдържанието, вашият код го визуализира, а CEL ги свързва.