При роботі з документацією на Docusaurus часто потрібні дані із зовнішніх API, CMS або баз даних. Стандартний підхід — завантажувати їх у рантаймі — призводить до високого TTFB (до 3 секунд), N+1 запитів та проблем із hydration. Кастомний плагін вирішує це на етапі збірки: дані підвантажуються один раз, кешуються і впроваджуються в статичні сторінки. Жодних зайвих запитів від клієнта, жодного JS-оверхеду.
Розробляємо плагіни під ключ: від архітектури до деплою. У проєктах із GitHub API, Contentful або Strapi ми скорочуємо TTFB на 60–80% і автоматизуємо створення сторінок. Наприклад, для проєкту з 50 маршрутами з Contentful ми знизили TTFB з 2.5 до 0.15 секунди. Якщо ваш проєкт вимагає інтеграції нестандартних джерел, кастомний плагін — єдиний спосіб зберегти продуктивність і гнучкість.
Проблеми, які вирішуємо
- Високий TTFB та N+1 запити при завантаженні даних із GitHub, GitLab або власного бекенду — плагін кешує відповіді через
cacheTimeта об'єднує запити. Результат: TTFB падає з 2–3 секунд до 100–200 мс. - Ручна модифікація webpack-конфігу для підтримки YAML, GraphQL або JSX — плагін додає правила завантажувачів без втручання в
webpack.config.js. - Складність створення динамічних сторінок на основі зовнішніх даних — плагін генерує маршрути автоматично через хук
contentLoaded. Наприклад, сторінки для кожного релізу з GitHub Releases створюються без зайвого коду.
Чому варто використовувати кастомний плагін замість стандартних засобів?
Стандартні плагіни Docusaurus (наприклад, @docusaurus/plugin-content-docs) працюють тільки з локальними файлами. Якщо дані живуть в API, їх доводиться завантажувати в рантаймі, що вбиває продуктивність. Кастомний плагін переносить завантаження на етап збірки: використовує loadContent для асинхронного вибірки даних, кешує їх і віддає в contentLoaded для генерації сторінок. Це дає статичні сторінки з даними, які оновлюються при кожному білді. Жодної залежності від мережі на стороні користувача.
Типовий кейс: плагін для Contentful
Для одного з проєктів ми розробили плагін, який завантажував записи з Contentful, мапив на MDX-шаблони та створював сторінки за 20 маршрутами. У результаті час завантаження сторінки скоротився на 70%, а контент-менеджери отримали можливість оновлювати документацію без звернення до розробників.
Порівняння стандартного підходу та кастомного плагіна
| Характеристика | Стандартні засоби | Кастомний плагін |
|---|---|---|
| Інтеграція API | Обмежена, тільки статичні файли | Повна, з кешуванням та повторним використанням |
| TTFB | Високий при прямих запитах (1–3 с) | Оптимізовано через loadContent (0.1–0.2 с) |
| Гнучкість | Низька — ручне редагування markdown | Висока — автоматична генерація сторінок |
| Складність підтримки | Зростає з кожним новим джерелом | Модульна, легко розширюється |
Як працює lifecycle плагіна Docusaurus?
Плагін Docusaurus реалізує кілька lifecycle-хуків, кожен з яких відповідає за певний етап збірки. Основні хуки: loadContent (асинхронне завантаження даних), contentLoaded (генерація контенту на основі завантажених даних), configureWebpack (модифікація webpack-конфігу) та postBuild (фінальна обробка). Розробник плагіна може визначити тільки необхідні хуки. Наприклад, якщо потрібно просто додати глобальні стилі, достатньо configureWebpack. Для завантаження даних з API обов'язкові loadContent та contentLoaded.
Порівняння lifecycle-хуків
| Хук | Призначення | Типове використання |
|---|---|---|
loadContent |
Асинхронне завантаження даних з API | Вибірка даних, кешування |
contentLoaded |
Генерація сторінок на основі даних | Створення маршрутів та MDX-сторінок |
postBuild |
Постобробка готового сайту | Генерація sitemap, додаткові скрипти |
Що робити, якщо плагін не завантажує дані?
Найчастіша причина — помилка в конфігурації опцій плагіна. Переконайтеся, що в docusaurus.config.js правильно вказані параметри apiUrl, cacheTime та source. Друга поширена проблема — неправильний формат відповіді API: плагін очікує JSON, а сервер повертає XML. У таких випадках використовуйте трансформери даних всередині loadContent. Нарешті, перевірте, що плагін імпортовано коректно і його експорт відповідає інтерфейсу PluginModule. Всі ці помилки ми виявляємо на етапі тестування та надаємо детальний лог.
Що входить у розробку плагіна?
Архітектурне проєктування — обираємо оптимальні хуки, структуру даних та спосіб кешування. Реалізація на TypeScript з валідацією опцій та обробкою помилок. Інтеграція та тестування на staging з реальними даними. Документація та деплой: README, приклад конфігурації, налаштування CI для автозбірки.
Процес роботи
- Аналіз вимог — визначаємо джерела даних, формат вихідних сторінок та необхідні lifecycle-хуки.
- Проєктування — описуємо архітектуру плагіна, опції та контракти.
- Розробка — пишемо код на TypeScript, надаємо проміжні збірки для тестування.
- Тестування — перевіряємо коректність завантаження, обробку помилок та продуктивність.
- Деплой та підтримка — розгортаємо в production, передаємо документацію та проводимо консультацію.
Терміни орієнтовно
Розробка плагіна для завантаження зовнішніх даних та створення сторінок займає від 2 до 5 днів залежно від складності. Вартість розраховується індивідуально — зв'яжіться для оцінки вашого проєкту.
Що ви отримуєте
- Вихідний код плагіна з коментарями та документацією.
- Приклад конфігурації та виклику в
docusaurus.config.js. - Налаштування CI/CD для автоматичної збірки.
- Консультацію щодо подальшого розвитку та підтримку протягом місяця.
Більше 5 років досвіду в розробці на React та Node.js, реалізовано понад 50 плагінів для Docusaurus та інших систем документації. Гарантуємо сумісність з останніми версіями Docusaurus.
Отримайте консультацію з архітектури вашого плагіна. Зв'яжіться з нами для аналізу вашого завдання — ми підготуємо пропозицію за один день.
