Лучшие практики
Модули дают большую силу — важно не ухудшить производительность и удобство разработки.
Асинхронный setup
Модуль может быть асинхронным (запрос к API и т.п.), но Nuxt ждёт завершения setup перед следующим модулем и стартом режима разработки или сборки. Тяжёлую работу лучше откладывать на хуки.
setup длится больше секунды, Nuxt выведет предупреждение.Префиксы в API {#prefix-your-exports}
Явный префикс у конфигов, плагинов, API, композаблов, компонентов и серверных маршрутов снижает конфликты с другими модулями, ядром и кодом пользователя.
Лучше по имени модуля, например nuxt-foo:
| Тип | ❌ Так не надо | ✅ Лучше |
|---|---|---|
| Компоненты | <Button>, <Modal> | <FooButton>, <FooModal> |
| Композаблы | useData(), useModal() | useFooData(), useFooModal() |
| Сервер | /api/track, /api/data | /api/_foo/track, /api/_foo/data |
Серверные маршруты
Пути вроде /api/auth, /api/login, /api/user часто заняты приложением. Используйте уникальный префикс:
/api/_foo/.../_foo/...для не-API маршрутов
Хуки вместо тяжёлого setup
Разовые задачи (генерация конфигов, миграции схемы БД, установка зависимостей) выполняйте в хуках жизненного цикла модуля, а не целиком в 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) {
// Обычная логика setup на каждой сборке
addServerHandler({ /* ... */ })
},
})
Так меньше лишней работы на каждой сборке. Подробнее см. документацию Nuxt Kit по модулям — в типах defineNuxtModule есть поля onInstall и onUpgrade.
Дружба с TypeScript
В Nuxt первоклассная поддержка TypeScript. Типы в модуле помогают даже тем, кто пишет на JS.
Синтаксис ESM
Nuxt рассчитан на нативный ESM — см. ESM в Nuxt.
Документация
В README имеет смысл описать:
- зачем модуль
- как подключить и использовать
- что именно делает
Ссылка на сайт интеграции и полную документацию обязательна.
Демо
Полезно приложить минимальный пример и ссылку на StackBlitz в README — так проще попробовать модуль и воспроизвести баги.
Без привязки к «Nuxt 3» в названии
Пишите «X для Nuxt», а ограничения версий задавайте через meta.compatibility, чтобы не дробить экосистему.
Соглашения стартера
Стартер задаёт ESLint и прочие дефолты. Если модуль открыт для контрибьюций, те же настройки упрощают ревью и единый стиль с другими модулями сообщества.