Розробка кастомних 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%.