Проблема типізації безголової WordPress

Безголова WordPress означає, що WordPress служить як CMS, а окремий JavaScript фронтенд (Next.js, Astro, Nuxt тощо) рендерить сторінки. Фронтенд отримує контент через REST API або WPGraphQL і відображає його. Для простого контенту — заголовка, анотації, зображення — типи TypeScript вбудовані в більшість SDK.

Проблема полягає в кастомних полях. Кастомні поля визначаються плагінами, а не ядром WordPress. TypeScript не знає, що ваша група полів “Hero Section” має title: string, subtitle: string, background_image: WPImage та cta_button: { text: string; url: string; }. Код фронтенду, який отримує доступ до data.hero_title, не має типізації — помилки в написанні, відсутні поля та рефакторинг перейменувань полів стають помилками під час виконання.

Рішення, які існували до Field Forge:

• Писати типи вручну — нудно і виходить з синхронізації, коли ви редагуєте групи полів у WordPress
• Використовувати загальний any — знецінює мету TypeScript
• Використовувати Zod або подібну валідацію під час виконання — додає шаблонний код до кожного API виклику
• Використовувати генерацію коду з GraphQL схеми — працює, якщо ви використовуєте WPGraphQL + GraphQL Code Generator, але складно налаштувати

Field Forge пропонує простіший шлях: автоматично генерувати визначення TypeScript безпосередньо з ваших груп полів.

---

Як це працює

Крок 1: Створіть групу полів у Field Forge

Ви проектуєте групу полів у візуальному конструкторі — скажімо, “Hero Section” з полями для заголовка, підзаголовка, фонової картинки та кнопки CTA.

Крок 2: Натисніть “Завантажити TypeScript”

На екрані адміністрування групи полів Field Forge має кнопку “Завантажити TypeScript”, яка генерує файл .d.ts, що містить визначення типів для всіх ваших груп полів.

Крок 3: Використовуйте типи у вашому фронтенді

Збережіть файл .d.ts у вашому репозиторії фронтенду (або скопіюйте-вставте в існуючий файл типів). Тепер TypeScript знає точну структуру даних кожної групи полів.

“`typescript import { HeroSectionFields } from ‘./types/fieldforge.d.ts’;

function Hero({ data }: { data: HeroSectionFields }) { return (

{data.title}

{data.subtitle}

{data.cta_button.text}

); } “`

TypeScript виявляє помилки в написанні, відсутні поля та неправильні типи під час компіляції. Автозаповнення IDE працює. Рефакторинг безпечний.

---

Відображення типів полів

Кожен тип поля Field Forge має відповідний тип TypeScript:

Поле Field Forge	Тип TypeScript
Текст	string
Текстова область	string
Число	number
Діапазон	number
Електронна пошта	string
URL	string
Пароль	string (чутливий)
Зображення	WPImage (вбудований інтерфейс)
Файл	WPFile
WYSIWYG	string (HTML)
oEmbed	string (вбудований HTML)
Галерея	WPImage[]
Вибір (один)	`’option_a’	‘option_b’	‘option_c’` (літеральний союз виборів)
Вибір (багато)	`Array<'option_a'	‘option_b’>`
Чекбокс	string[]
Радіо	`’option_a’	‘option_b’`
Так/Ні	boolean
Група кнопок	`’option_a’	‘option_b’`
Взаємозв’язок	WPPost[]
Об’єкт поста	WPPost
Посилання на сторінку	string (URL)
Таксономія	WPTerm[] або WPTerm (залежно від налаштувань)
Користувач	WPUser або WPUser[]
Вибір дати	string (ISO формат)
Вибір часу	string
Вибір кольору	string (hex або rgba)
Повторювач	Array (вкладений тип)
Група	вкладений тип
Гнучкий контент	`Array<LayoutA	LayoutB	LayoutC>` (дискримінований союз)
Клон	посилання на клоновану групу

Вбудовані типи

Сгенерований .d.ts Field Forge включає допоміжні типи, які ви будете використовувати у всьому вашому фронтенді:

“`typescript interface WPImage { id: number; url: string; alt: string; width: number; height: number; sizes: { thumbnail: string; medium: string; large: string; full: string; }; }

interface WPFile { id: number; url: string; filename: string; mime_type: string; filesize: number; }

interface WPPost { id: number; title: string; slug: string; content: string; excerpt: string; date: string; modified: string; featured_image: WPImage | null; categories: WPTerm[]; tags: WPTerm[]; }

interface WPUser { id: number; name: string; email: string; avatar: string; }

interface WPTerm { id: number; name: string; slug: string; description: string; } “`

---

Приклад: Група полів Hero

Група полів під назвою “Hero Section” з заголовком, підзаголовком, фоновим зображенням та кнопкою CTA генерує:

“typescript export interface HeroSectionFields { title: string; subtitle: string; background_image: WPImage; cta_button: { text: string; url: string; open_in_new_tab: boolean; }; } “

Використання в компоненті Next.js:

“`typescript import type { HeroSectionFields } from ‘@/types/fieldforge’;

interface Props { hero: HeroSectionFields; }

export function Hero({ hero }: Props) { return (

{hero.title}

{hero.subtitle}

<a href={hero.cta_button.url} target={hero.cta_button.open_in_new_tab ? '_blank' : undefined}

{hero.cta_button.text}

); } “`

Кожна властивість має тип. TypeScript виявляє hero.titel (помилка в написанні), hero.background_image.URL (неправильний регістр) та hero.cta_button.open_new_tab (неправильна назва поля) під час компіляції.

---

Типи повторювачів

Поля повторювача стають Array. Вкладені повторювачі працюють рекурсивно:

“typescript export interface TeamPageFields { team_members: Array<{ name: string; photo: WPImage; bio: string; skills: Array; }>; } “

TypeScript розуміє вкладеність. Ітерація по team_members і потім skills повністю типізована.

---

Гнучкий контент як дискриміновані союзи

Поля гнучкого контенту генерують дискриміновані союзи — рідна функція TypeScript для обробки масивів з кількома типами:

“`typescript type HeroLayout = { acf_fc_layout: ‘hero’; title: string; subtitle: string; background_image: WPImage; };

type FeaturesLayout = { acf_fc_layout: ‘features’; section_title: string; features: Array; };

type CTALayout = { acf_fc_layout: ‘cta’; headline: string; button: { text: string; url: string }; };

export interface LandingPageFields { page_sections: Array; } “`

У вашому компоненті фронтенду використовуйте охорону типу, щоб відобразити правильний макет:

“typescript function PageSections({ sections }: { sections: LandingPageFields['page_sections'] }) { return ( {sections.map((section, i) => { if (section.acf_fc_layout === 'hero') { return ; } if (section.acf_fc_layout === 'features') { return ; } if (section.acf_fc_layout === 'cta') { return ; } })} “

Всередині кожного блоку if TypeScript звужує section до правильного типу. Кастинг не потрібен.

---

Процес регенерації

Коли ви редагуєте групи полів у адмініструванні Field Forge, типи змінюються. Щоб зберегти ваш фронтенд у синхронізації:

1. Редагуйте групу полів у WordPress
2. Натисніть “Завантажити TypeScript” в адмініструванні Field Forge
3. Замініть файл .d.ts у вашому репозиторії фронтенду
4. Збережіть зміни

Або автоматизуйте це через REST API Field Forge:

“`bash

Отримайте останні визначення TypeScript через curl

curl https://wp.example.com/wp-json/fieldforge/v1/typescript > types/fieldforge.d.ts “`

Додайте це до вашого конвеєра збірки фронтенду, і типи завжди будуть актуальними.

---

Працює з будь-яким фронтенд-фреймворком

Типи TypeScript є незалежними від фреймворку. Сгенеровані типи Field Forge працюють з:

• Next.js — на базі React, відмінна інтеграція TypeScript
• Astro — архітектура островів, чудово підходить для контентних сайтів
• Nuxt — на базі Vue, інтеграція Nuxt Content
• SvelteKit — на базі Svelte, вбудована підтримка TypeScript
• Remix — на базі React, серверний підхід
• Vanilla TypeScript — будь-який фронтенд, що використовує TypeScript

---

Готові до типізованої безголової WordPress?

Отримайте Field Forge — від $35/рік →

Генерація TypeScript включена в кожен платний план. Жоден інший плагін кастомних полів WordPress не має цієї функції.