14. Modules

📦 Модули Nuxt 3

Модули — это основная единица расширения Nuxt-экосистемы. Они позволяют добавлять функциональность в приложение через конфигурацию nuxt.config.ts, автоматически настраивая плагины, composables, компоненты и серверные маршруты.

---

🌟 Популярные модули экосистемы

Nuxt имеет богатую экосистему официальных и сторонних модулей:

@nuxtjs/tailwindcss

Интеграция Tailwind CSS с автоматической генерацией конфигурации:

npx nuxi module add tailwindcss

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxtjs/tailwindcss'],
  tailwindcss: {
    cssPath: ['~/assets/css/tailwind.css', { injectPosition: 'first' }],
    configPath: 'tailwind.config',
    exposeConfig: {
      level: 2
    },
    viewer: true
  }
})

@nuxt/image

Оптимизация изображений с поддержкой множества провайдеров:

npx nuxi module add image

export default defineNuxtConfig({
  modules: ['@nuxt/image'],
  image: {
    quality: 80,
    format: ['webp'],
    screens: {
      xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, xxl: 1536
    },
    providers: {
      cloudinary: {
        baseURL: 'https://res.cloudinary.com/demo/image/upload/'
      }
    }
  }
})

@nuxt/content

Файловая CMS с поддержкой Markdown, MDX, JSON:

npx nuxi module add content

export default defineNuxtConfig({
  modules: ['@nuxt/content'],
  content: {
    highlight: {
      theme: 'github-dark',
      langs: ['js', 'ts', 'vue', 'bash', 'json']
    },
    markdown: {
      anchorLinks: true
    }
  }
})

@pinia/nuxt

Управление состоянием с Pinia:

npx nuxi module add @pinia/nuxt

export default defineNuxtConfig({
  modules: ['@pinia/nuxt'],
  pinia: {
    storesDirs: ['./stores/**']
  }
})

@nuxtjs/i18n

Интернационализация приложения:

npx nuxi module add i18n

export default defineNuxtConfig({
  modules: ['@nuxtjs/i18n'],
  i18n: {
    locales: ['en', 'ru', 'de'],
    defaultLocale: 'ru',
    strategy: 'prefix_except_default'
  }
})

---

🔧 Создание собственного модуля

Структура модуля

my-module/
├── src/
│   ├── module.ts        # основной файл модуля
│   ├── runtime/
│   │   ├── composables/
│   │   │   └── useMyFeature.ts
│   │   ├── components/
│   │   │   └── MyComponent.vue
│   │   └── plugins/
│   │       └── my-plugin.ts
├── package.json
└── playground/           # тестовое приложение
    └── nuxt.config.ts

defineNuxtModule

src/module.ts

import { defineNuxtModule, addPlugin, createResolver, addImports, addComponent } from '@nuxt/kit'

export interface ModuleOptions {
  apiKey: string
  baseURL: string
  timeout?: number
  debug?: boolean
}

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'my-awesome-module',
    configKey: 'myModule',
    compatibility: {
      nuxt: '^3.0.0'
    }
  },
  defaults: {
    apiKey: '',
    baseURL: 'https://api.example.com',
    timeout: 5000,
    debug: false
  },
  async setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    // Добавляем плагин
    addPlugin(resolver.resolve('./runtime/plugins/my-plugin'))

    // Автоимпорт composables
    addImports({
      name: 'useMyFeature',
      as: 'useMyFeature',
      from: resolver.resolve('./runtime/composables/useMyFeature')
    })

    // Автоимпорт компонентов
    addComponent({
      name: 'MyComponent',
      filePath: resolver.resolve('./runtime/components/MyComponent.vue')
    })

    // Передача опций в runtime через runtimeConfig
    nuxt.options.runtimeConfig.public.myModule = {
      baseURL: options.baseURL,
      debug: options.debug
    }

    // Приватные опции (только сервер)
    nuxt.options.runtimeConfig.myModule = {
      apiKey: options.apiKey
    }

    if (options.debug) {
      console.log('[my-module] Инициализация с настройками:', options)
    }
  }
})

---

🔌 Runtime-часть модуля

src/runtime/plugins/my-plugin.ts

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig()

  const client = {
    async fetch(endpoint: string, options = {}) {
      return await $fetch(endpoint, {
        baseURL: config.public.myModule.baseURL,
        ...options
      })
    }
  }

  return {
    provide: {
      myClient: client
    }
  }
})

src/runtime/composables/useMyFeature.ts

export function useMyFeature() {
  const config = useRuntimeConfig()
  const data = ref(null)
  const loading = ref(false)
  const error = ref(null)

  async function fetch(endpoint: string) {
    loading.value = true
    error.value = null
    try {
      data.value = await $fetch(endpoint, {
        baseURL: config.public.myModule.baseURL
      })
    } catch (err) {
      error.value = err
    } finally {
      loading.value = false
    }
  }

  return { data, loading, error, fetch }
}

---

🛠️ Утилиты Nuxt Kit

@nuxt/kit предоставляет богатый набор утилит для создания модулей:

import {
  defineNuxtModule,
  addPlugin,
  addComponent,
  addImports,
  addServerHandler,
  addTemplate,
  addRouteMiddleware,
  extendPages,
  extendRouteRules,
  createResolver,
  installModule,
  hasNuxtModule,
  requireModule,
  logger
} from '@nuxt/kit'

export default defineNuxtModule({
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url)

    // Добавление серверного маршрута
    addServerHandler({
      route: '/api/my-module',
      handler: resolver.resolve('./runtime/server/api/handler')
    })

    // Добавление middleware
    addRouteMiddleware({
      name: 'my-middleware',
      path: resolver.resolve('./runtime/middleware/my-middleware')
    })

    // Добавление шаблона (генерация файла)
    addTemplate({
      filename: 'my-module.d.ts',
      getContents: () => `
declare module '#my-module' {
  export const useMyFeature: () => any
}
      `
    })

    // Установка зависимого модуля
    if (!hasNuxtModule('@pinia/nuxt')) {
      installModule('@pinia/nuxt')
    }

    // Расширение конфигурации маршрутов
    extendRouteRules('/my-module/**', {
      headers: { 'X-My-Module': 'true' }
    })

    // Логирование
    logger.info('my-module: инициализирован успешно')
  }
})

---

📋 Использование в nuxt.config.ts

nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    // Строкой (модуль из node_modules)
    '@nuxtjs/tailwindcss',

    // Функцией (локальный модуль)
    './modules/my-local-module',

    // С опциями через массив
    ['@nuxtjs/i18n', {
      defaultLocale: 'ru',
      locales: ['ru', 'en']
    }],

    // Через отдельные ключи конфигурации (рекомендуется)
    '@pinia/nuxt'
  ],

  // Настройки модулей через отдельные ключи
  tailwindcss: {
    viewer: process.env.NODE_ENV === 'development'
  },

  pinia: {
    storesDirs: ['./stores/**', './features/**/stores/**']
  }
})

---

🏗️ Локальные модули

modules/analytics/index.ts

import { defineNuxtModule, addPlugin, createResolver } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'local-analytics',
    configKey: 'analytics'
  },
  defaults: {
    enabled: true,
    trackingId: ''
  },
  setup(options, nuxt) {
    if (!options.enabled) return

    const resolver = createResolver(import.meta.url)
    addPlugin(resolver.resolve('./plugin'))

    nuxt.options.runtimeConfig.public.analyticsId = options.trackingId
  }
})

---

📊 Топ модулей по категориям

Категория	Модуль	Описание
UI	@nuxtjs/tailwindcss	Utility-first CSS
UI	@nuxt/ui	Компонентная библиотека
Данные	@pinia/nuxt	Управление состоянием
Данные	@nuxt/content	Файловая CMS
Медиа	@nuxt/image	Оптимизация изображений
Auth	@sidebase/nuxt-auth	Аутентификация
i18n	@nuxtjs/i18n	Интернационализация
SEO	@nuxtjs/sitemap	Генерация sitemap
SEO	@nuxtjs/robots	robots.txt
Dev	@nuxt/devtools	Инструменты разработки

---