Лучшие практики

Модули дают много возможностей — ниже практики, которые помогут сохранить производительность и удобство разработки.

Асинхронный setup

Модули Nuxt могут быть асинхронными (например, запрос к API или вызов async-функции).

Учитывайте, что Nuxt ждёт завершения setup модуля перед следующим модулем и запуском dev-сервера или сборки. Долгую логику лучше переносить в хуки Nuxt.

Префиксы экспортов

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

Желательно использовать имя модуля. Например, для модуля nuxt-foo:

Серверные маршруты

Для серверных маршрутов это особенно важно: пути вроде /api/auth, /api/login, /api/user часто уже заняты приложением.

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

• /api/_foo/... (подчёркивание в префиксе)
• /_foo/... (для не-API маршрутов)

Хуки жизненного цикла

Если модулю нужны разовые действия (генерация конфигов, настройка БД, установка зависимостей), используйте хуки жизненного цикла, а не логику в основном setup.

import { addServerHandler, defineNuxtModule } from 'nuxt/kit'
import semver from 'semver'

export default defineNuxtModule({
  meta: {
    name: 'my-database-module',
    version: '1.0.0',
  },
  async onInstall (nuxt) {
    // Разовая настройка: схема БД, конфиги и т.д.
    await generateDatabaseConfig(nuxt.options.rootDir)
  },
  async onUpgrade (nuxt, options, previousVersion) {
    // Миграции между версиями
    if (semver.lt(previousVersion, '1.0.0')) {
      await migrateLegacyData()
    }
  },
  setup (options, nuxt) {
    // Обычная логика при каждой сборке
    addServerHandler({ /* ... */ })
  },
})

Так вы избегаете лишней работы при каждой сборке. Подробнее — в документации по хукам.

Поддержка TypeScript

В Nuxt TypeScript поддерживается из коробки. Экспорт типов и разработка модуля на TypeScript помогают пользователям даже тем, кто не пишет на TypeScript.

Синтаксис ESM

Nuxt опирается на нативный ESM. Подробнее — Нативные ES-модули.

Документация модуля

Имеет смысл описать в README:

• Зачем нужен модуль?
• Как использовать?
• Что именно делает модуль?

Полезно давать ссылки на сайт интеграции и документацию.

Демо

Хорошая практика — минимальный пример с модулем на StackBlitz и ссылка на него в README. Пользователям будет проще попробовать модуль и собрать воспроизведение при багах.

Версионная нейтральность

Nuxt, Nuxt Kit и связанные инструменты разрабатываются с учётом обратной и прямой совместимости.

Используйте формулировки вроде «X для Nuxt», а не «X для Nuxt 3», чтобы не дробить экосистему. Ограничения по версии Nuxt задавайте через meta.compatibility.

Соглашения стартового шаблона

В стартовом шаблоне модуля есть набор инструментов и конфигов (например, ESLint). Если планируете открыть модуль, следование этим настройкам выравнивает стиль кода с модулями сообщества и упрощает контрибьюцию.