Вклад

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

Вы можете внести свой вклад в экосистему Nuxt разными способами.

Экосистема

Экосистема Nuxt включает в себя множество различных проектов и организаций:

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

Как внести вклад

Решение проблем и помощь в обсуждениях

Просмотрите задачи и обсуждения проекта, которому хотите помочь. Для Nuxt: задачи и обсуждения. Ответы другим, обходные пути, воспроизведение бага кодом или короткое расследование с выводами — всё это очень ценно.

Создание задачи на GitHub

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

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

Мы стараемся следовать внутренней схеме разбора задач.

Оформление запроса на слияние (pull request)

Мы всегда рады вашим PR! ❤️

Прежде чем начать

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

Если вы делаете новую возможность, сначала откройте задачу с запросом на функцию, чтобы с сопровождающими согласовать цель и дизайн. Так экономится время и у сопровождающих, и у авторов, а релизы выходят быстрее. Задача должна быть подтверждена кем-то из команды фреймворка, прежде чем в PR появится реализация.

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

Крупные изменения в ядре Nuxt разумно начинать с модуля: так быстрее проверить идею. Дальше можно оформить RFC обсуждением, собрать отзывы и либо перенести в ядро, либо оставить отдельным модулем.

Конвенции о коммитах

Сообщения коммитов оформляйте по Conventional Commits — так удобно собирать changelog. Если формат нов для вас, прочитайте спецификацию целиком.

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

  • fix: typo → docs: fix typo

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

Как открыть PR

Как создать запрос на слияние на GitHub, описано в официальной справке.

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

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

В одном PR может быть несколько коммитов: повторный rebase и force push не обязательны — при слиянии мы обычно в интерфейсе GitHub выбираем Squash and merge (слияние с объединением коммитов в один).

Хуки коммитов в репозитории не навешиваем, чтобы не тормозить работу. Перед отправкой PR прогоните линтер и тесты локально.

В PR не должно быть левых правок: случайные пробелы и форматирование в стороне от сути — откатите. Не смешивайте в одном PR несколько несвязанных фич или фиксов; если можно разделить — откройте несколько PR. Один PR = одна задача.

После открытия PR

После отправки мы постараемся ответить как можно скорее.

Если назначен сопровождающий, он ведёт ревью и правки по этому PR.

Просьба доработать PR и красные индикаторы в интерфейсе GitHub не значат, что работа «плохая» — так отображается статус в списке.

Метка pending («в ожидании») — внутренняя пометка команды: часто остаются шаги до финального ревью; она не отражает качество идеи. Причину по возможности поясним в комментарии.

Ревью и ответы по PR выстраиваем по внутренней схеме.

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

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

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

  • Комментарии, описания задач и PR пишите своими словами.
  • Важнее ясный человеческий текст, чем «идеальная» грамматика.
  • Не вставляйте сгенерированные ИИ-резюме без своего понимания.

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

  • ИИ для черновика кода или идей — нормально.
  • В репозиторий — только то, что вы понимаете и можете объяснить.
  • Вклад должен отражать ваш ход мыслей и решение задачи.

Наша цель — качество и удовольствие от совместной работы с реальными людьми. Если у вас есть идеи, как улучшить политику по ИИ в сообществе Nuxt, расскажите нам! ❤️

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

Сделали в Nuxt что-то полезное — вынесите в модуль, чтобы этим могли пользоваться другие. Каталог модулей уже большой, но места для новых хватает.

Если вам нужна помощь при создании модуля, не стесняйтесь обращаться к нам.

Создание RFC

Сначала лучше сделать модуль и проверить крупную идею на сообществе.

Если модуль уже есть или он не подходит, откройте обсуждение: чётко опишите замысел, приложите примеры кода или сигнатуры для новых API, ссылки на связанные задачи и болевые точки.

Если тема подходит под RFC, мы сменим категорию и расширим охват для обратной связи.

Затем RFC проходит стадии (метки на GitHub):

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

Конвенции по всей экосистеме

Следующие соглашения являются обязательными в организации nuxt/ и рекомендуются для других сопровождающих в экосистеме.

Конвенция модулей

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

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

Мы рекомендуем следующие библиотеки, которые используются во всей экосистеме:

  • pathe - универсальные утилиты путей (замена для path от node)
  • ufo - утилиты для парсинга и объединения URL-адресов
  • unbuild - система сборки на основе rollup
  • ... проверьте остальные части организации 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 либо настройте IDE по разделу ESLint.

Если в редакторе стоит Prettier, отключите его для этого репозитория, чтобы не было конфликтов правил.

Менеджер пакетов

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

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

Чтобы включить его, выполните команду:

Терминал
corepack enable

Это нужно сделать только один раз, после установки Node.js на ваш компьютер.

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

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

Вот несколько советов, которые могут помочь улучшить вашу документацию:

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