Участие в разработке

Nuxt — проект сообщества, и мы рады любому вкладу! ❤️

Участвовать в экосистеме Nuxt можно по-разному.

Экосистема

В экосистему Nuxt входят разные проекты и организации:

  • nuxt/ — основные репозитории фреймворка. nuxt/nuxt содержит Nuxt (версии 2 и 3).
  • nuxt-modules/ — модули и библиотеки от сообщества. Есть процесс переноса модуля в nuxt-modules; у модулей свои мейнтейнеры, без зависимости от одного человека.
  • unjs/ — многие библиотеки используются в экосистеме Nuxt. Они задуманы как универсальные, без привязки к фреймворку и окружению. Вклад и использование другими фреймворками приветствуются.

Как участвовать

Триаж issues и помощь в обсуждениях

Просматривайте issues и обсуждения интересующих проектов. Например: доска issues и обсуждения Nuxt. Помощь другим, обмен обходными путями, создание воспроизведений или разбор бага с описанием выводов очень помогают.

Создание issue

Спасибо, что нашли время создать issue! ❤️

  • Сообщение о багах: см. наш гайд перед созданием issue.
  • Запросы функций: проверьте, нет ли уже issue или обсуждения по этой теме. Если функция относится к другой части экосистемы (например, модулю), лучше создать запрос там. Если идея общая или API неочевиден, можно открыть обсуждение в категории Ideas.

Мы по возможности следуем внутренней блок-схеме по принятию решений по issues при ответах на issues.

Pull Request

Pull request'ы всегда приветствуются! ❤️

Перед началом

Перед исправлением бага лучше проверить, есть ли issue с его описанием — возможно, это вопрос документации или есть контекст, который стоит учесть.

Для новой функции сначала откройте issue с запросом функции, чтобы обсудить с мейнтейнерами необходимость и дизайн. Это сэкономит время и ускорит выход фичи. Issue должен подтвердить участник команды фреймворка перед реализацией в PR.

Опечатки лучше собирать в один PR для более чистой истории коммитов.

Для крупных изменений в Nuxt рекомендуем сначала создать модуль Nuxt и реализовать фичу там (быстрый proof-of-concept), затем создать RFC в виде обсуждения. После принятия сообществом и сбора отзывов фичу можно доработать и включить в ядро Nuxt или оставить отдельным модулем.

Соглашения по коммитам

Используем Conventional Commits; по ним автоматически генерируется changelog. Прочитайте гайд, если ещё не знакомы.

fix: и feat: — для изменений кода (влияющих на логику). Для опечаток и правок документов используйте docs: или chore::

  • fix: typo → docs: fix typo

В монорепо (например, nuxt/nuxt) указывайте scope в скобках: feat(kit): add 'addMagicStuff' utility.

Оформление PR

Если не знаете, как отправить PR, см. гайд GitHub.

Заголовок PR тоже должен следовать соглашениям по коммитам.

Если PR закрывает существующие issues — укажите их в описании.

Несколько коммитов в одном PR допустимы; не обязательно делать rebase или force push — при мерже используем «Squash and Merge».

Мы не добавляем pre-commit хуки, чтобы не мешать быстрым коммитам. Перед отправкой PR убедитесь, что проходят lint/test.

Старайтесь не включать в один PR несвязанные изменения (например, правки пробелов или форматирования в других частях файла). Один PR — одна задача.

После отправки PR

Мы по возможности оперативно просматриваем PR.

Назначение мейнтейнера означает, что он уделит ревью особое внимание и при необходимости внесёт правки.

Если просят изменения — не пугайтесь красного текста: это способ быстро видеть статус списка PR, а не оценка качества.

Статус «pending» обычно означает внутреннюю заметку по ревью, а не мнение о PR. По возможности поясним в комментарии.

Мы по возможности следуем блок-схеме по принятию решений по PR при ответах и ревью.

Вклад с помощью ИИ

Мы приветствуем осмысленное использование ИИ при контрибуции в Nuxt и просим следовать двум принципам.

Не позволяйте ИИ говорить за вас

  • Комментарии, issues и описания PR должны быть написаны вашим голосом.
  • Ценим ясное человеческое общение выше идеальной грамматики.
  • Не копируйте готовые саммари от ИИ, если они не отражают ваше понимание.

Не позволяйте ИИ думать за вас

  • Можно использовать ИИ для генерации кода или идей.
  • Отправляйте только тот вклад, который вы полностью понимаете и можете объяснить.
  • Вклад должен отражать вашу логику и подход к решению.

Цель — качество и радость от общения с живыми людьми. Если есть идеи по политике использования ИИ в сообществе Nuxt — напишите! ❤️

Создание модуля

Сделали что-то полезное на Nuxt? Можно оформить это как модуль и поделиться с другими. Модулей уже много, но места хватит ещё.

Нужна помощь при разработке — обращайтесь.

RFC

Рекомендуем сначала создать модуль для проверки крупной фичи и принятия сообществом.

Если это уже сделано или модуль не подходит — начните с нового обсуждения. Чётко изложите идею, приведите примеры кода или сигнатуры API, укажите существующие issues или боли с примерами.

Если мы сочтём это RFC, сменим категорию на RFC и шире запросим отзывы.

Этапы RFC:

  • rfc: active — открыт для комментариев
  • rfc: approved — одобрен командой Nuxt
  • rfc: ready to implement — создан issue и назначен исполнитель
  • rfc: shipped — реализован
  • rfc: archived — не одобрен, но сохранён для справки

Соглашения в экосистеме

В организации nuxt/ следующие соглашения обязательны; в остальной экосистеме — рекомендуются.

Модули

Модули должны следовать шаблону Nuxt-модуля. Подробнее — гайд по модулям.

Использование библиотек unjs

Рекомендуемые библиотеки, используемые в экосистеме:

  • pathe — универсальные утилиты для путей (замена node path)
  • ufo — разбор и склейка URL
  • obuild — сборка на rolldown
  • … и другие в unjs/

ESM и type: module

Большая часть экосистемы Nuxt потребляет ESM. Рекомендуем избегать CJS-специфичного кода (__dirname, require). Подробнее — про ESM.

Corepack

Corepack обеспечивает использование нужной версии пакетного менеджера. В проектах может быть поле packageManager в package.json.

При такой конфигурации Corepack установит pnpm v7.5.0 (если его ещё нет) и будет использовать его для команд.

package.json
{
  "packageManager": "pnpm@7.5.0"
}

ESLint

Используем ESLint для линтинга и форматирования с @nuxt/eslint.

Настройка IDE

Рекомендуем VS Code с расширением ESLint. При сохранении можно включить авто-исправление и форматирование:

settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll": "never",
    "source.fixAll.eslint": "explicit"
  }
}

Без Prettier

ESLint уже настроен на форматирование, дублировать его Prettier не нужно. Для форматирования: yarn lint --fix, pnpm lint --fix, bun run lint --fix или deno run lint --fix, либо настройка в разделе ESLint.

Если в редакторе установлен Prettier — лучше отключить его при работе с проектом, чтобы не было конфликтов.

Пакетный менеджер

Рекомендуем pnpm для модулей, библиотек и приложений.

Важно включить Corepack, чтобы версия менеджера совпадала с проектом. Corepack встроен в свежие версии Node.

Включение (один раз после установки Node):

Terminal
corepack enable

Руководство по стилю документации

Документация — важная часть Nuxt. Мы стремимся быть интуитивным фреймворком, и во многом это зависит от качества документации и DX в экосистеме. 👌

Несколько советов:

  • По возможности избегайте субъективных слов вроде просто, очевидно, всего лишь — у читателей разный опыт, эти слова не несут смысла и могут обидеть.
    Просто убедитесь, что функция возвращает промис.
    Убедитесь, что функция возвращает промис.
  • Предпочитайте активный залог.
    Ошибка будет выброшена Nuxt.
    Nuxt выбросит ошибку.
Как контрибьютить в документацию