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

> Быстрые и поддерживаемые модули Nuxt: рекомендации авторам.

Модули дают большую силу — важно не ухудшить производительность и удобство разработки.

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

Модуль может быть асинхронным (запрос к API и т.п.), но Nuxt **ждёт** завершения `setup` перед следующим модулем и стартом режима разработки или сборки. Тяжёлую работу лучше откладывать на хуки.

<warning>

Если `setup` длится **больше секунды**, Nuxt выведет предупреждение.

</warning>

## Префиксы в API {#prefix-your-exports}

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

Лучше по имени модуля, например `nuxt-foo`:

<table>
<thead>
  <tr>
    <th>
      Тип
    </th>
    
    <th>
      ❌ Так не надо
    </th>
    
    <th>
      ✅ Лучше
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Компоненты
    </td>
    
    <td>
      <code>
        <Button>
      </code>
      
      , <code>
        <Modal>
      </code>
    </td>
    
    <td>
      <code>
        <FooButton>
      </code>
      
      , <code>
        <FooModal>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Композаблы
    </td>
    
    <td>
      <code>
        useData()
      </code>
      
      , <code>
        useModal()
      </code>
    </td>
    
    <td>
      <code>
        useFooData()
      </code>
      
      , <code>
        useFooModal()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Сервер
    </td>
    
    <td>
      <code>
        /api/track
      </code>
      
      , <code>
        /api/data
      </code>
    </td>
    
    <td>
      <code>
        /api/_foo/track
      </code>
      
      , <code>
        /api/_foo/data
      </code>
    </td>
  </tr>
</tbody>
</table>

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

Пути вроде `/api/auth`, `/api/login`, `/api/user` часто заняты приложением. Используйте уникальный префикс:

- `/api/_foo/...`
- `/_foo/...` для не-API маршрутов

## Хуки вместо тяжёлого setup

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

```ts
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 по модулям](/docs/3.x/api/kit/modules) — в типах `defineNuxtModule` есть поля `onInstall` и `onUpgrade`.

## Дружба с TypeScript

В Nuxt первоклассная поддержка TypeScript. Типы в модуле помогают даже тем, кто пишет на JS.

## Синтаксис ESM

Nuxt рассчитан на нативный ESM — см. [ESM в Nuxt](/docs/3.x/guide/concepts/esm).

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

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

- зачем модуль
- как подключить и использовать
- что именно делает

Ссылка на сайт интеграции и полную документацию обязательна.

## Демо

Полезно приложить минимальный пример и ссылку на [StackBlitz](https://nuxt.new/s/v4) в README — так проще попробовать модуль и воспроизвести баги.

## Без привязки к «Nuxt 3» в названии

Пишите «X для Nuxt», а ограничения версий задавайте через `meta.compatibility`, чтобы не дробить экосистему.

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

Стартер задаёт ESLint и прочие дефолты. Если модуль открыт для контрибьюций, те же настройки упрощают ревью и единый стиль с другими [модулями сообщества](/modules).