Розробка кастомних Contentful Apps (розширень)

Розробка кастомних Contentful Apps (розширень)

Стандартний редактор Contentful зручний, але для бізнес-процесів з унікальною логікою часто не вистачає вбудованих полів. Доводиться вивантажувати дані, обробляти зовнішніми інструментами, витрачати час на ручне введення. Ми розробляємо кастомні Contentful Apps — розширення, що вбудовуються прямо в інтерфейс редактора. Це не просто віджети: через SDK застосунок отримує доступ до Entry API, Space API та Server-side App Actions. З нашими рішеннями клієнти скорочують час публікації контенту на 30–50% і виключають помилки ручного перенесення.

За час роботи з headless CMS ми створили понад 20 кастомних App для клієнтів з e-commerce, медіа та фінансів. Гарантуємо сумісність з актуальними версіями Contentful і безшовну інтеграцію в існуючий воркфлоу. Кастомні Apps у 4 рази швидші за ручну обробку контенту — це підтверджують дані наших проєктів.

Архітектура Contentful App

Кожен застосунок складається з двох частин: frontend (React/Vue/Vanilla JS, розміщується на будь-якому хостингу) та опційний App Backend (AWS Lambda або будь-який HTTP-ендпоінт для App Actions і Events). Обидва реєструються в App Definition через Contentful Management API або Web App.

App Definition ├── Locations: field, sidebar, entry-editor, page, home ├── Parameters: instance params (per-field) + installation params (per-space) └── App Actions: serverless functions callable from UI or API 

Типові сценарії:

• Кастомний field editor — наприклад, колірний пікер, пов'язаний з дизайн-токенами з Figma
• Sidebar extension — панель SEO-аналізу, яка читає поля Entry у реальному часі
• Page location — повноекранний Asset Manager з інтеграцією Cloudinary
• App Actions — генерація AI-описів через OpenAI при збереженні Entry

Як розробити кастомне поле Contentful?

Для field extension використовується SDK @contentful/app-sdk. Наприклад, колірний пікер з прив'язкою до дизайн-токенів:

import { init, FieldExtensionSDK } from '@contentful/app-sdk'; init((sdk: FieldExtensionSDK) => { const value = sdk.field.getValue(); sdk.field.onValueChanged((newValue) => setFieldValue(newValue)); sdk.field.setValue({ color: '#ff5500', token: 'brand-primary' }); sdk.window.startAutoResizer(); }); 

Для React-застосунків застосовуємо @contentful/react-apps-toolkit:

import { useSDK, useFieldValue } from '@contentful/react-apps-toolkit'; const ColorPickerField = () => { const sdk = useSDK<FieldExtensionSDK>(); const [value, setValue] = useFieldValue<string>(); return ( <ColorPicker value={value} onChange={(color) => setValue(color.hex)} tokens={sdk.parameters.installation.designTokens} /> ); }; 

Що таке App Actions і навіщо вони потрібні?

App Actions — серверні функції, які викликаються з UI редактора без кастомного бекенду. Contentful проксіює запит на ваш endpoint і повертає результат. Приклад — генерація SEO-описів через OpenAI:

const result = await sdk.cma.appAction.callById({ spaceId: sdk.ids.space, environmentId: sdk.ids.environment, appDefinitionId: sdk.ids.app, appActionId: 'generate-seo', parameters: { entryId: sdk.ids.entry, locale: sdk.locales.default }, }); 

На сервері (Node.js/Express):

app.post('/actions/generate-seo', async (req, res) => { verifySignature(req.headers['x-contentful-signature'], req.body); const { entryId, locale } = req.body.parameters; const entry = await cma.entry.get({ entryId }); const seoData = await openai.chat.completions.create({ model: 'gpt-4o', messages: [{ role: 'user', content: buildSeoPrompt(entry, locale) }], }); res.json({ result: { seoTitle: seoData.choices[0].message.content } }); }); 

Installation Parameters і конфігурація

Параметри встановлення задаються один раз при інсталяції застосунку в Space. Через них передаються API-ключі, токени, конфіги — без хардкоду в коді застосунку:

const ConfigScreen = () => { const sdk = useSDK<AppExtensionSDK>(); const [params, setParams] = useState(sdk.parameters.installation); sdk.app.onConfigure(() => ({ parameters: params, targetState: { EditorInterface: { controls: [{ fieldId: 'seoTitle', widgetId: sdk.ids.app }], }, }, })); }; 

Чому кастомні Contentful Apps вигідніші за стандартні рішення?

Кастомні Apps інтегруються безпосередньо в редактор, економлячи час на перемикання між сервісами. На відміну від сторонніх плагінів, вони повністю контролюють логіку та дані. Наприклад, SEO-аналіз у сайдбарі дозволяє маркетологу одразу бачити помилки заповнення — це виключає перезавантаження сторінок і правки в останній момент. Наші клієнти фіксують скорочення циклу публікації в 2–3 рази після впровадження кастомного App.

Збірка та деплой

Contentful надає CLI для локальної розробки та деплою:

npx create-contentful-app@latest my-app --template typescript npm run start contentful-app-scripts activate npm run build contentful-app-scripts upload 

Налаштувати CI/CD для Contentful App нескладно: ми використовуємо GitHub Actions для автоматичного тестування та деплою. Після пуша в main запускається збірка, проганяються тести з моками @contentful/app-sdk, і через contentful-app-scripts upload завантажується нова версія в Contentful CDN. Це гарантує, що ваше розширення завжди оновлене без ручних операцій.

Строки та обсяг робіт

При розробці обов'язково покриваємо тестами з @contentful/app-sdk mock-об'єктами та налаштовуємо CI для автоматичного деплою через contentful-app-scripts upload.

Як ми гарантуємо якість?

Кожне розширення проходить код-рев'ю, тестується в ізольованому середовищі та отримує документацію для кінцевих користувачів. Ми даємо гарантію на стабільність роботи з актуальними версіями Contentful і оперативно адаптуємо застосунок при оновленні SDK. Документація Contentful App SDK підтверджує коректність нашого підходу. Зв'яжіться з нами — оцінимо ваш сценарій за 1 робочий день. Замовте розробку Contentful App під ключ і отримайте економію часу на контент-публікацію до 50%.