Nitro

Утилиты Nuxt Kit для Nitro: серверные обработчики, плагины и маршруты пререндера.

Nitro — TypeScript-фреймворк с открытым кодом для быстрых веб-серверов. Nuxt (при необходимости — Nuxt Bridge) строит сервер на Nitro. Кратко по API Kit: useNitro — экземпляр Nitro; addServerHandler — обработчик; addDevServerHandler — только в режиме разработки; addServerPlugin — плагин рантайма Nitro; addPrerenderRoutes — маршруты пререндера.

`addServerHandler`

Регистрирует обработчик Nitro — для серверного middleware или своего маршрута.

Использование

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

export default defineNuxtModule({
  setup (options) {
    const { resolve } = createResolver(import.meta.url)

    addServerHandler({
      route: '/robots.txt',
      handler: resolve('./runtime/robots.get'),
    })
  },
})

Тип

function addServerHandler (handler: NitroEventHandler): void

Параметры

handler: объект обработчика со свойствами:

Свойство	Тип	Обязательно	Описание
`handler`	`string`	`true`	Путь к обработчику события.
`route`	`string`	`false`	Префикс пути или маршрут. Пустая строка — режим прослойки (middleware).
`middleware`	`boolean`	`false`	Явно помечает middleware: вызывается на каждом запросе; обычно не завершает ответ, а передаёт управление дальше.
`lazy`	`boolean`	`false`	Ленивая подгрузка обработчика по запросу.
`method`	`string`	`false`	Сопоставление HTTP-метода; если метод есть в имени файла обработчика, он подставляется по умолчанию.

Примеры

Базовый пример

Добавление обработчика из модуля через addServerHandler.

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

export default defineNuxtModule({
  setup (options) {
    const { resolve } = createResolver(import.meta.url)

    addServerHandler({
      route: '/robots.txt',
      handler: resolve('./runtime/robots.get'),
    })
  },
})

export default defineEventHandler(() => {
  return {
    body: `User-agent: *\nDisallow: /`,
  }
})

Запрос к /robots.txt вернёт такой ответ:

User-agent: *
Disallow: /

`addDevServerHandler`

Регистрирует обработчик Nitro только в режиме разработки; в сборку для продакшена не включается.

Использование

import { defineEventHandler } from 'h3'
import { addDevServerHandler, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addDevServerHandler({
      handler: defineEventHandler(() => {
        return {
          body: `Ответ, сгенерированный в ${new Date().toISOString()}`,
        }
      }),
      route: '/_handler',
    })
  },
})

Тип

// @errors: 2391
import type { NitroDevEventHandler } from 'nitropack'
// ---cut---
function addDevServerHandler (handler: NitroDevEventHandler): void

Параметры

handler: объект со свойствами:

Свойство	Тип	Обязательно	Описание
`handler`	`EventHandler`	`true`	Обработчик события.
`route`	`string`	`false`	Префикс или маршрут; пустая строка — прослойка (middleware).

Примеры

Базовый пример

Иногда нужен обработчик только в режиме разработки — например просмотр конфигурации Tailwind.

import { joinURL } from 'ufo'
import { addDevServerHandler, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  async setup (options, nuxt) {
    const route = joinURL(nuxt.options.app?.baseURL, '/_tailwind')

    // @ts-expect-error Динамический импорт опциональной dev-зависимости.
    const createServer = await import('tailwind-config-viewer/server/index.js').then(r => r.default || r) as any
    const viewerDevMiddleware = createServer({ tailwindConfigProvider: () => options, routerPrefix: route }).asMiddleware()

    addDevServerHandler({ route, handler: viewerDevMiddleware })
  },
})

`useNitro`

Возвращает экземпляр Nitro.

Вы можете вызывать useNitro() только после хука ready.

Изменения конфигурации уже созданного экземпляра Nitro не подхватываются.

Использование

import { defineNuxtModule, useNitro } from '@nuxt/kit'

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

    nuxt.hook('ready', () => {
      const nitro = useNitro()
      // работа с экземпляром Nitro
    })
  },
})

Тип

function useNitro (): Nitro

`addServerPlugin`

Подключает плагин, расширяющий поведение Nitro в runtime.

Подробнее о плагинах Nitro — в документации Nitro.

В файле плагина явно импортируйте defineNitroPlugin из nitropack/runtime. То же касается утилит вроде useRuntimeConfig.

Использование

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

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)
    addServerPlugin(resolve('./runtime/plugin.ts'))
  },
})

Тип

function addServerPlugin (plugin: string): void

Параметры

Свойство	Тип	Обязательно	Описание
`plugin`	`string`	`true`	Путь к плагину. Ожидается default-export — функция с экземпляром Nitro.

Примеры

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

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)
    addServerPlugin(resolve('./runtime/plugin.ts'))
  },
})

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', (event) => {
    console.log('при запросе', event.path)
  })

  nitroApp.hooks.hook('beforeResponse', (event, { body }) => {
    console.log('при ответе', event.path, { body })
  })

  nitroApp.hooks.hook('afterResponse', (event, { body }) => {
    console.log('после ответа', event.path, { body })
  })
})

`addPrerenderRoutes`

Добавляет маршруты в список пререндера Nitro.

Использование

import { addPrerenderRoutes, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  meta: {
    name: 'nuxt-sitemap',
    configKey: 'sitemap',
  },
  defaults: {
    sitemapUrl: '/sitemap.xml',
    prerender: true,
  },
  setup (options) {
    if (options.prerender) {
      addPrerenderRoutes(options.sitemapUrl)
    }
  },
})

Тип

function addPrerenderRoutes (routes: string | string[]): void

Параметры

Свойство	Тип	Обязательно	Описание
`routes`	`string \| string[]`	`true`	Один маршрут или массив для пререндера.

`addServerImports`

Регистрирует серверные автоимпорты: символы доступны в Nitro без явных import.

Если утилита должна работать и на сервере, и на клиенте и использоваться из shared/, импортируйте её из одного и того же файла и для addImports, и для addServerImports, с одинаковой сигнатурой. Этот файл не должен тянуть контекстно-зависимые вещи (Nitro, Nuxt app), иначе возможны ошибки при проверке типов.

Использование

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

export default defineNuxtModule({
  setup (options) {
    const names = [
      'useStoryblok',
      'useStoryblokApi',
      'useStoryblokBridge',
      'renderRichText',
      'RichTextSchema',
    ]

    names.forEach(name =>
      addServerImports({ name, as: name, from: '@storyblok/vue' }),
    )
  },
})

Тип

function addServerImports (dirs: Import | Import[]): void

Параметры

Первый аргумент — объект или массив объектов со свойствами:

Свойство	Тип	Обязательно	Описание
`name`	`string`	`true`	Имя для автоимпорта.
`from`	`string`	`true`	Спецификатор модуля.
`priority`	`number`	`false`	Приоритет; при совпадении имён выбирается импорт с большим приоритетом.
`disabled`	`boolean`	`false`	Отключить этот импорт.
`meta`	`Record<string, any>`	`false`	Метаданные импорта.
`type`	`boolean`	`false`	Только типовой импорт.
`typeFrom`	`string`	`false`	Значение `from` при генерации объявлений типов.
`as`	`string`	`false`	Импортировать под этим именем.

`addServerImportsDir`

Добавляет каталог, который Nitro сканирует для автоимпорта.

Использование

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

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerImportsDir(resolve('./runtime/server/composables'))
  },
})

Тип

function addServerImportsDir (dirs: string | string[], opts: { prepend?: boolean }): void

Параметры

Свойство	Тип	Обязательно	Описание
`dirs`	`string \| string[]`	`true`	Каталог или массив каталогов для сканирования Nitro.
`opts`	`{ prepend?: boolean }`	`false`	При `prepend: true` каталог ставится в начало списка сканирования.

Примеры

addServerImportsDir подключает каталог к сканированию Nitro — удобно для собственных server-композаблов с автоимпортом.

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

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerImportsDir(resolve('./runtime/server/composables'))
  },
})

export function useApiSecret () {
  const { apiSecret } = useRuntimeConfig()
  return apiSecret
}

В серверном коде можно вызывать useApiSecret:

runtime/server/api/hello.ts

const useApiSecret = (): string => ''
// ---cut---
export default defineEventHandler(() => {
  const apiSecret = useApiSecret()
  // использование apiSecret
})

`addServerScanDir`

Добавляет каталоги, которые Nitro сканирует так же, как ~/server: регистрируются те же подкаталоги по тем же правилам.

Сканируются только ~/server/api, ~/server/routes, ~/server/middleware и ~/server/utils.

Использование

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

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerScanDir(resolve('./runtime/server'))
  },
})

Тип

function addServerScanDir (dirs: string | string[], opts: { prepend?: boolean }): void

Параметры

Свойство	Тип	Обязательно	Описание
`dirs`	`string \| string[]`	`true`	Каталог(и), регистрируемые как server-директории для сканирования Nitro.
`opts`	`{ prepend?: boolean }`	`false`	При `prepend: true` каталог ставится в начало списка сканирования.

Примеры

addServerScanDir подключает каталог с server-структурой, аналогичной ~/server.

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

export default defineNuxtModule({
  meta: {
    name: 'my-module',
    configKey: 'myModule',
  },
  setup (options) {
    const { resolve } = createResolver(import.meta.url)
    addServerScanDir(resolve('./runtime/server'))
  },
})

export function hello () {
  return 'Привет из серверных утилит!'
}

Функцию hello можно вызывать в серверном коде.

runtime/server/api/hello.ts

function hello () {
  return 'Привет из серверных утилит!'
}
// ---cut---
export default defineEventHandler(() => {
  return hello() // то же, что возвращает hello()
})

Был ли материал полезен?

Сообщить об ошибке или Редактировать на GitHub

Шаблоны

Утилиты Nuxt Kit для шаблонов и генерации дополнительных файлов в разработке и при сборке.

Разрешение путей

Утилиты Nuxt Kit для разрешения путей: относительно модуля, с неизвестным именем файла или расширением.