Что такое модули (modules) Nuxt? Чем они отличаются от плагинов?

Модули и плагины Nuxt: в чём разница

Модули и плагины решают разные задачи на разных этапах жизненного цикла Nuxt. Модули — это расширения времени сборки (build-time), плагины — это код, выполняемый во время инициализации приложения (runtime).

Плагины (Plugins)

Плагины запускаются при каждом старте приложения — на сервере при SSR и на клиенте после гидратации. Они получают доступ к Nuxt app instance и Vue.

// plugins/my-plugin.ts
export default defineNuxtPlugin((nuxtApp) => {
  // Регистрируем глобальную директиву Vue
  nuxtApp.vueApp.directive('focus', {
    mounted(el) {
      el.focus();
    }
  });

  // Предоставляем утилиту через provide/inject
  return {
    provide: {
      formatPrice: (amount: number, currency: string) =>
        new Intl.NumberFormat('ru-RU', { style: 'currency', currency }).format(amount)
    }
  };
});

// Использование в компоненте
<script setup lang="ts">
const { $formatPrice } = useNuxtApp();
const price = $formatPrice(1200, 'USD'); // '$1,200.00'
</script>

Суффикс файла управляет окружением:

• my-plugin.ts — выполняется и на сервере, и на клиенте
• my-plugin.client.ts — только на клиенте
• my-plugin.server.ts — только на сервере

Модули (Modules)

Модули работают на этапе сборки (в Nuxt Kit). Они могут добавлять компоненты, composables, server-роуты, изменять конфигурацию webpack/vite, регистрировать плагины программно, добавлять хуки Nuxt. Модули — это то, что вы видите в nuxt.config.ts в массиве modules.

// modules/my-module.ts
import { defineNuxtModule, addPlugin, createResolver, addComponent } from '@nuxt/kit';

export default defineNuxtModule({
  meta: {
    name: 'my-analytics',
    configKey: 'analytics'
  },
  defaults: {
    trackingId: '',
    debug: false
  },
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url);

    // Добавляем runtime-плагин из модуля
    addPlugin({
      src: resolver.resolve('./runtime/plugin'),
      mode: 'client'
    });

    // Добавляем компонент
    addComponent({
      name: 'AnalyticsPageView',
      filePath: resolver.resolve('./runtime/components/PageView.vue')
    });

    // Передаём конфиг в runtimeConfig для использования в плагине
    nuxt.options.runtimeConfig.public.analyticsId = options.trackingId;

    // Добавляем хук
    nuxt.hook('build:done', () => {
      console.log('Analytics module: build complete');
    });
  }
});

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    './modules/my-module',
    // или npm-пакет:
    '@nuxtjs/tailwindcss'
  ],
  analytics: {
    trackingId: 'GA-XXXXX',
    debug: true
  }
});

Ключевые отличия

• Время выполнения: модули — сборка, плагины — runtime.
• Доступ: модули используют Nuxt Kit API (addComponent, addPlugin, addServerHandler); плагины — Vue app API и Nuxt composables.
• Конфигурация: модули принимают настройки через nuxt.config.ts с typesafe дефолтами; плагины конфигурируются через runtimeConfig или env-переменные.
• Распространение: модули публикуются как npm-пакеты с полным контролем над build pipeline; плагины — просто файлы, которые можно скопировать.

Когда что использовать

• Плагин — если нужно добавить что-то в Vue instance, зарегистрировать директиву, инициализировать клиентскую библиотеку (Sentry, Pinia store).
• Модуль — если нужно добавить компоненты/composables в auto-import, изменить webpack/vite конфиг, добавить server-роуты, создать переиспользуемую функциональность для нескольких проектов.

Подводные камни

• Плагины с .client.ts суффиксом не выполняются при SSR — если компонент обращается к $myPlugin во время серверного рендера, получите ошибку «undefined».
• Порядок загрузки плагинов — алфавитный; числовые префиксы (01.analytics.ts) — единственный способ гарантировать порядок.
• Модули должны использовать createResolver(import.meta.url) для резолва путей — абсолютные пути не работают при публикации в npm.
• Изменения в файлах модуля не всегда подхватываются hot reload — нужен полный рестарт dev-сервера.
• addPlugin внутри модуля добавляет плагин в bundle приложения, даже если пользователь не использует эту функциональность — добавляйте только необходимое.
• Типизация для provide в плагинах требует дополнения модуля TypeScript через declare module '#app' — без этого useNuxtApp().$myUtil будет иметь тип any.
• Модули имеют доступ к nuxt.options на этапе сборки, но не к runtime-данным (запросам, пользователям) — это только для конфигурации.

• Путать Nuxt modules с похожим API из соседнего фреймворка.
• Не объяснять, где код выполняется: сервер, клиент, build step или runtime.
• Игнорировать влияние на hydration, cache, bundle size или безопасность.

• Точно объясняет назначение механизма «Nuxt modules».
• Показывает корректный минимальный пример без выдуманных API.
• Называет ограничения, failure modes и production-компромиссы.