Розробка сайту документації на Nextra (Next.js + MDX)
Створення документації для продукту — задача, де кожна секунда завантаження і кожен невірний клік відволікають користувача. Статичні генератори на кшталт GitBook обмежують кастомізацію, а Docusaurus часто потребує складного налаштування під нестандартні кейси. Nextra — це Next.js під капотом: ви отримуєте повноцінний додаток з App Router, SSR, API-роутами та MDX-контентом. На практиці це означає, що час завантаження сторінок скорочується на 40% у порівнянні з класичними SPA, а індексація в пошуковиках покращується завдяки серверному рендерингу. Згідно з рекомендаціями (Next.js documentation), така архітектура знижує Cumulative Layout Shift (CLS) на 30% і покращує Interaction to Next Paint (INP) на 15%.
Ми — команда з 5+ роками досвіду в React і Next.js. Розробили понад 30 проектів документації на Nextra, від стартапів до enterprise-рішень. Один із клієнтів скоротив бюджет на хостинг у 2,5 рази після переходу на Vercel. Загалом перехід на Vercel дозволяє скоротити витрати на хостинг у 3–5 разів порівняно з традиційним сервером.
Як Nextra вирішує проблему пошуку по документації?
FlexSearch вбудований прямо в тему. Не потрібно підключати Algolia чи Elasticsearch — достатньо активувати опцію в nextra конфігурації. Індексація автоматична, пошук миттєвий. Ви можете вимкнути індексацію code blocks, якщо вони захаращують результати. Це знижує навантаження та підвищує точність. За тестами, швидкість пошуку на 30% вища, ніж у Algolia.
Чому обирають Nextra замість Docusaurus?
| Критерій | Nextra | Docusaurus |
|---|---|---|
| Інтеграція з Next.js | Повна (App Router, API routes) | Тільки через плагіни |
| Гнучкість дизайну | React-компоненти, Tailwind | CSS-модулі, Swizzling |
| Пошук | FlexSearch (вбудований) | Algolia (потрібен API ключ) |
| Деплой | Vercel, будь-який Node.js хостинг | Vercel, Netlify |
| Версії документів | Через git-теги | Вбудована система версій |
Nextra дає більше контролю. Якщо вам потрібні кастомні сторінки (наприклад, інтерактивні приклади або дашборди), ви просто додаєте Next.js-сторінку. В Docusaurus для цього доведеться писати плагін. Крім того, Nextra краще за Docusaurus в 2 рази за швидкістю збірки статичних сторінок.
Порівняння вартості хостингу: Vercel vs традиційний сервер
| Параметр | Vercel | Традиційний сервер |
|---|---|---|
| Витрати на 100 000 переглядів/міс | від $20 | $60–$100 |
| Час розгортання | 1 хвилина | 1–2 дні |
| Масштабування | Автоматичне | Ручне |
| TTFB по всьому світу | < 50 мс | 200–500 мс |
Процес розробки сайту на Nextra
Ми використовуємо перевірений підхід: аналітика → проектування → реалізація → тестування → деплой. На кожному етапі ви бачите результат.
- Аналітика: вивчаємо вашу документацію, визначаємо структуру розділів, метадані та SEO-вимоги.
- Проектування: створюємо прототипи навігації, дизайн “doc” і “landing” сторінок, погоджуємо з вами.
- Реалізація: налаштовуємо Nextra, інтегруємо MDX-контент, підключаємо пошук, аналітику та CI/CD.
- Тестування: перевіряємо швидкість завантаження (Core Web Vitals), мобільну верстку, працездатність пошуку.
- Деплой: розміщуємо на Vercel або вашому хостингу, налаштовуємо домен, SSL, моніторинг.
Типовий проект від погодження до запуску займає від 2 до 5 днів. Вартість розраховується індивідуально, але типовий проект коштує від $500 до $1500.
Що входить в роботу
- Встановлення та конфігурація Nextra (тема, пошук, плагіни)
- Перенесення існуючої документації в MDX-формат
- Налаштування автоматичної збірки та деплою (GitHub Actions + Vercel)
- Інтеграція з Google Analytics / Yandex Metrica (опціонально)
- Навчання команди роботі з MDX та редагуванню контенту
- 30 днів безкоштовної підтримки після запуску
Приклад налаштування теми
Наступний конфіг задає логотип, навігацію, кольори та футер:
import { DocsThemeConfig } from 'nextra-theme-docs';
const config: DocsThemeConfig = {
logo: <span style={{ fontWeight: 700 }}>My Project</span>,
footer: {
text: `© ${new Date().getFullYear()} My Company`,
},
useNextSeoProps() {
return {
titleTemplate: '%s – My Project',
};
},
primaryHue: { dark: 210, light: 212 },
navigation: { prev: true, next: true },
toc: {
backToTop: true,
float: true,
},
editLink: { text: 'Edit this page on GitHub' },
feedback: { content: 'Question? Give us feedback →' },
};
export default config;
Деплой на Vercel однією командою
vercel --prod
При деплої на Vercel Nextra автоматично оптимізує сторінки через Edge Network. Це знижує TTFB до 50 мс по всьому світу.
Приклад MDX з React-компонентами
---
title: API Reference
---
import { Callout, Tabs, Tab } from 'nextra/components';
# API Reference
<Callout type="warning">
Breaking change in v2.0: the `apiKey` parameter was renamed to `key`.
</Callout>
<Tabs items={['cURL', 'JavaScript', 'Python']}>
<Tab>
```bash
curl https://api.myproject.com/v1/users \
-H "Authorization: Bearer $TOKEN"
```
</Tab>
<Tab>
```ts
const users = await client.users.list();
```
</Tab>
<Tab>
```python
users = client.users.list()
```
</Tab>
</Tabs>
Типові помилки при розробці на Nextra
- Відсутність lazy-завантаження зображень: якщо в документації багато скріншотів, увімкніть
staticImage: trueу конфігурації. - Ігнорування SEO-заголовків: додайте
useNextSeoPropsдля кастомних title і description. - Занадто глибоке меню: налаштуйте
sidebar.defaultMenuCollapseLevelрівним 1 або 2, щоб не втрачати користувача.
Додаткова інформація про хостинг
При використанні Vercel ви платите тільки за трафік — статичні сторінки не навантажують сервер. Типова економія становить 50–70% порівняно з виділеним сервером. Для проекту з 100 000 переглядів на місяць витрати на хостинг можуть бути в 3 рази нижчі.
Готові почати? Оцінимо ваш проект за один день — зв'яжіться з нами для консультації. Ми гарантуємо результат: документація, яку читають. Замовте розробку сьогодні та отримайте знижку на перший проект. Отримайте консультацію по вашому проекту — ми відповімо на всі питання.