VuePress vs VitePress: что выбрать?

Практически для любого нового сайта документации на Vue выбирайте VitePress.

Если вам недавно приходилось поддерживать в живом состоянии сайт на VuePress 1, вы знаете характерный признак: вы сохраняете Markdown-файл, а затем идёте искать себе другое занятие, пока webpack пересобирает проект. Именно этот разрыв во времени и составляет большую часть сути данного сравнения.

VitePress — это генератор статических сайтов, официально рекомендованный командой Vue; VuePress 1 объявлен устаревшим, а VuePress 2 поддерживается сообществом и до сих пор находится в статусе release candidate. Выбирайте VuePress 2 только тогда, когда вам действительно нужно то, что он пока делает лучше, — например, собственный API плагинов и тем или более простую подмену компонентов. А если вам необходимо встроенное версионирование документации, обратите внимание на генератор на базе React, такой как Docusaurus.

В этой статье мы обоснуем такой выбор через конкретные различия, которые действительно определяют судьбу проекта документации: динамика развития проекта, скорость цикла разработки, компромисс в области кастомизации и то, чего VitePress по-настоящему пока не умеет. Кроме того, мы скорректируем устаревший тезис «VitePress — это альфа-версия», который до сих пор встречается в старых сравнениях.

Что активно поддерживается: VuePress или VitePress?

Динамика развития проекта — главный фактор при принятии этого решения, и он однозначно указывает в одну сторону. VitePress продолжает то, на чём остановился VuePress, реализуя ту же идею «Markdown в документацию» на Vue 3 и Vite. Команда Vue пришла к выводу, что не может одновременно поддерживать два генератора, и остановилась на VitePress как на рекомендуемом, прекратив поддержку VuePress 1 и передав VuePress 2 команде сообщества.

Картина зрелости обратна тому, что утверждают старые статьи. Стабильный — именно VitePress: npm по-прежнему указывает 1.6.4 как последний релиз, а changelog относит следующую мажорную ветку к альфе — 2.0.0-alpha.19. Репозиторий ядра VuePress до сих пор описывает свой статус как release candidate, то есть VuePress 2 так и не дошёл до финального стабильного релиза. На VitePress также работает документация Vite, Rollup, Pinia, VueUse, Vitest, D3, UnoCSS, Iconify и самого сайта Vue.js.

Опыт разработки: Vite против webpack

Цикл разработки — именно то, чем VitePress выделяется. VuePress 1 построен на Vue 2 и webpack, что быстро устарело; VitePress работает на Vue 3 и Vite. Официальная документация оценивает интервал между сохранением файла и появлением изменений на экране менее чем в 100 миллисекунд — без перезагрузки страницы и без ожидания запуска dev-сервера. Это цикл обратной связи совершенно иного класса, чем пересборка webpack.

Архитектура вывода тоже важна. В режиме разработки dev-сервер запускается на порту 5173, если вы не укажете другой. В production первая страница, на которую попадает посетитель, — это предварительно отрендеренный статический HTML, который быстро загружается и хорошо индексируется; затем VitePress гидратирует её в Vue-приложение (SPA), поэтому все последующие переходы происходят в браузере, как объясняется в посте о релизе 1.0. VitePress также включает локальный полнотекстовый поиск, до которого одна опция конфигурации, и Shiki — тот же подсветчик синтаксиса, что используется в VS Code, так что ни то, ни другое не нужно подключать вручную.

Конфигурация и кастомизация: реальный компромисс

Вот в чём честное противоречие. У VitePress более простая конфигурация и действительно сильная тема по умолчанию, но глубокая кастомизация означает написание кода на Vue. У VitePress по замыслу нет собственной системы плагинов: кастомизация делегируется Vue через пользовательские темы и слоты, а также Vite — через его конфигурацию и плагины. VuePress 2 сохраняет более широкий, собственный API плагинов и тем и делает подмену компонентов в конфигурации более прямолинейной — именно поэтому команды, глубоко ушедшие в кастомизированный сайт на VuePress, иногда остаются на нём.

У такого дизайна есть практические шероховатости. Переопределение scoped-стилей внутри Vue-компонентов темы по умолчанию иногда вынуждает прибегать к !important. Сайдбар гораздо проще и поддерживает отдельный сайдбар для каждой подпапки, но вы прописываете его вручную в themeConfig.sidebar: новый Markdown-файл не появится, пока вы не отредактируете конфигурацию или не добавите плагин от сообщества, например vitepress-sidebar. Frontmatter легко читается непосредственно внутри Markdown, а ссылки prev/next выводятся из сайдбара, если вы не задали prev и next самостоятельно — они могут указывать на любую страницу, независимо от того, есть ли она в сайдбаре.

Конфигурация сайдбара в VitePress выглядит аккуратно:

// .vitepress/config.ts
export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        collapsed: true,
        items: [
          { text: 'Introduction', link: '/guide/' },
          { text: 'Getting Started', link: '/guide/getting-started' },
        ],
      },
    ],
  },
}

Используйте форму объекта с ключами-путями (sidebar: { '/guide/': [...] }), когда вам нужен отдельный сайдбар для каждого раздела. Это тот самый паттерн с несколькими сайдбарами, который VuePress реализует сложнее.

Когда VitePress — неверный выбор?

VitePress намеренно ограничен по охвату, и несколько пробелов вполне реальны. В нём нет встроенного версионирования документации: команды, которые одновременно поддерживают v1/v2/v3, держат отдельные папки для версий и вручную настраивают сайдбары — это основная причина выбрать Docusaurus. Его экосистема плагинов невелика по сравнению с Docusaurus. Со блогами дела обстоят слабо: нет встроенной системы тегов, RSS-фида или страницы архива, поэтому сайт с сильным маркетинговым уклоном потребует больше усилий, чем он того стоит. И он требует Vue в тот момент, когда вы выходите за пределы Markdown и темы по умолчанию.

Выбирайте VitePress, если только вам конкретно не нужно встроенное версионирование или большая библиотека плагинов — это территория Docusaurus, — либо если ваш стек построен на React; в этом случае лучше подойдут Fumadocs, Nextra или Docusaurus.

Миграция с VuePress и итоговый вывод

Создание нового сайта на VitePress — это четыре команды: npm add -D vitepress, затем npx vitepress init для запуска мастера настройки, npm run docs:dev для локального сервера и npm run docs:build для генерации статики в .vitepress/dist. Актуальная официальная документация по умолчанию предлагает команду установки из ветки 2.0-alpha (vitepress@next) и указывает Node.js 22 или выше как обязательное требование, поэтому именно обычная команда npm add -D vitepress даёт вам стабильную 1.x.

Миграция с VuePress не сводится к простой замене. Ваш Markdown, frontmatter и общие расширения Markdown переносятся без проблем; схему конфигурации, тему и layout придётся переработать, а любым собственным плагинам VuePress понадобятся эквиваленты для VitePress. Проще всего миграция проходит на сайтах с темой по умолчанию.

Правило принятия решения: для нового сайта документации на Vue выбирайте VitePress и не оглядывайтесь. Если у вас сайт на VuePress с темой по умолчанию — переезжайте на VitePress. Если вам нужно встроенное версионирование или обширная библиотека плагинов — рассмотрите Docusaurus. А если ваш стек — React, начинайте сразу с генератора на базе React. Установите VitePress, запустите npx vitepress init, и у вас будет работающий сайт документации ещё до того, как вы дочитаете справочник по конфигурации.

Часто задаваемые вопросы

VuePress устарел?

VuePress 1 объявлен устаревшим и находится в режиме поддержки, а VuePress 2 был передан команде сообщества и остаётся release candidate, который так и не получил финальной стабильной версии. Команда Vue решила, что параллельная поддержка двух генераторов нецелесообразна, и теперь рекомендует VitePress как основной генератор статических сайтов. В npm тег 'latest' у ядра VuePress до сих пор указывает на ветку 1.x, что лишь подтверждает: 2.0 так и не вышел из статуса RC.

Может ли VitePress автоматически генерировать сайдбар на основе структуры папок?

Нет. По умолчанию VitePress не генерирует сайдбар автоматически. Новый Markdown-файл не появится, пока вы вручную не отредактируете сайдбар в файле конфигурации или не установите плагин от сообщества, например vitepress-sidebar. При этом VitePress поддерживает несколько сайдбаров с привязкой к путям, поэтому вы можете задать отдельный сайдбар для каждой подпапки, но это сопоставление задаётся явно, а не выводится из дерева каталогов.

Поддерживает ли VitePress версионирование документации, как Docusaurus?

Нет. В VitePress нет встроенной функции версионирования. Команды, которые поддерживают несколько версий документации одновременно, держат отдельные папки для версий и настраивают сайдбары вручную. Если версионированная документация с переключением через выпадающий список — жёсткое требование, то Docusaurus будет более сильным выбором, поскольку встроенное версионирование — одна из его ключевых возможностей. Это самая частая причина выбрать генератор на базе React вместо VitePress.

Почему VitePress требует написания Vue-компонентов для глубокой кастомизации?

У VitePress по замыслу нет собственной системы плагинов. Вместо отдельного API плагинов кастомизация делегируется Vue через пользовательские темы и слоты, а также Vite — через его конфигурацию и экосистему плагинов. Это позволяет сохранить ядро минимальным, но означает, что переопределение внешнего вида или поведения темы по умолчанию сводится к написанию Vue-компонентов и иногда к принудительному переопределению scoped-стилей через !important, а не к переключению опций конфигурации.