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

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 в экосистеме. 👌

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

Язык

  • Используйте американский английский в англоязычных фрагментах (behavior, а не behaviour; customize, а не customise).
  • Пишите названия инструментов и проектов с официальной капитализацией, даже если npm-пакет в нижнем регистре (например, PostCSS, а не postcss; Vite, а не vite; ESLint, а не eslint). Имя npm-пакета в нижнем регистре в обратных кавычках используйте только когда речь о самом пакете, например в инструкциях по установке.
    Nuxt supports postcss out of the box.
    Nuxt supports PostCSS out of the box. You don't need to install postcss manually.
    Регистр распространённых названий инструментов автоматически проверяется case police при запуске pnpm lint:docs.

Заголовки

  • Заголовки оформляйте по Chicago title case: с заглавной буквы первое слово, последнее слово и все значимые слова (существительные, глаголы, прилагательные, наречия, местоимения); артикли, союзы и предлоги — строчными независимо от длины (например, a, and, or, with, from, to). Если сомневаетесь, поможет capitalizemytitle.com.
    How to contribute to the docs
    How to Contribute to the Docs
  • Код в заголовках сохраняет исходный регистр и не учитывается при капитализации (например, Using useFetch in Components).

Inline-код

Оборачивайте в обратные кавычки:

  • Имена и пути файлов: nuxt.config.ts, server/api/
  • Имена npm-пакетов: @nuxt/kit, postcss
  • Ключи, опции и значения конфигурации: ssr: false, опция css
  • Идентификаторы кода — функции, composables, компоненты, переменные, типы: useFetch, <NuxtLink>, defineNuxtConfig
  • Команды терминала: npx nuxt init

Не используйте обратные кавычки для названий инструментов, проектов и общих понятий (пишите Vite, а не vite, когда речь об инструменте).

Примеры кода

  • Добавляйте имя файла к блокам кода, чтобы читатель понимал, куда поместить код. Если код не относится к конкретному файлу (например, команда shell), используйте метку вроде [Terminal].
    ```ts [nuxt.config.ts]
export default defineNuxtConfig({
  ssr: false,
})
```
  • Делайте примеры готовыми к копированию. Включайте нужные импорты и избегайте плейсхолдеров вроде ... в середине кода, который читатель вставит в проект. Читатель должен скопировать пример в проект и получить рабочий результат с минимальными правками.

Ссылки

  • На другие страницы документации ссылайтесь относительными путями без домена: /docs/4.x/getting-started/installation, а не https://nuxt.com/docs/4.x/getting-started/installation.
  • На внешние ресурсы ссылайтесь на конечный URL, а не на редирект. Проверить можно так:
    Terminal
    curl -sILo /dev/null -w '%{http_code} %{url_effective}\n' https://example.com/some-page

    Команда проходит по цепочке редиректов и выводит финальный статус и URL. Статус 200 с запрошенным URL означает, что ссылка в порядке. Если финальный URL отличается, ссылайтесь на него.

Тон

Стремитесь к дружелюбному и профессиональному тону. Обращайтесь к читателю напрямую («вы»), будьте лаконичны и исходите из добросовестности: у читателей разный бэкграунд и опыт, избегайте формулировок, которые могут показаться снисходительными. Тепло уместно — у документации может быть характер — но ясность всегда на первом месте.

Стиль написания

  • По возможности избегайте субъективных слов вроде просто, очевидно, всего лишь — у читателей разный опыт, эти слова не несут смысла и могут обидеть.
    Просто убедитесь, что функция возвращает промис.
    Убедитесь, что функция возвращает промис.
  • Предпочитайте активный залог.
    Ошибка будет выброшена Nuxt.
    Nuxt выбросит ошибку.
  • Используйте единые названия и порядок разделов в API-документации — composables, утилиты и компоненты. Включайте только подходящие разделы:
    1. Usage (Использование): как использовать API и типичные сценарии.
    2. Type (Тип): соответствующие TypeScript-декларации.
    3. Parameters (Параметры): каждый вход — тип, значение по умолчанию и доступные опции.
    4. Return Values (Возвращаемые значения): что возвращается и какого типа.
    5. Example (Пример): практический пример.

    Используйте именно эти названия разделов. Например, Parameters, а не Params, и Example, а не Examples.
  • В API-страницах (composables, utils, components) указывайте минимальную версию Nuxt, с которой доступна функция или утилита.
    Два уровня:
    • Глобально (вся страница): добавьте minimalVersion: "3.9" во frontmatter (без префикса «v»). Layout документации автоматически покажет badge версии как vX.Y (например, v3.9, v3.15).
    • Локально (конкретная опция или функция): добавьте badge рядом с опцией или разделом: :badge[v3.8]{color="info" size="xs" class="align-middle"} (например, для getCachedData в useFetch или режима navigation в callOnce).

    Версию можно найти в @since в JSDoc исходников, в release notes или в блоге Nuxt.
Как контрибьютить в документацию