Nitro (Kit)

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

Nitro — открытый TypeScript-фреймворк для быстрых веб-серверов. Nuxt использует Nitro как серверный движок. В 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`	да	Путь к обработчику событий.
`route`	`string`	нет	Префикс или маршрут. Пустая строка — middleware.
`middleware`	`boolean`	нет	Обработчик как middleware; вызывается на каждом маршруте, обычно без возврата значения.
`lazy`	`boolean`	нет	Ленивая загрузка обработчика.
`method`	`string`	нет	Совпадение HTTP-метода. Если имя файла содержит метод — используется по умолчанию.

Примеры

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

Добавление серверного обработчика из модуля:

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 только для режима разработки; в production-сборку не включается.

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

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

export default defineNuxtModule({
  setup () {
    addDevServerHandler({
      handler: defineEventHandler(() => {
        return {
          body: `Response generated at ${new Date().toISOString()}`,
        }
      }),
      route: '/_handler',
    })
  },
})

Тип

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

Параметры

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

Свойство	Тип	Обязательный	Описание
`handler`	`EventHandler`	да	Обработчик событий.
`route`	`string`	нет	Префикс или маршрут. Пустая строка — 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 - tailwind-config-viewer does not have correct types
    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`

Returns the Nitro instance.

You can call useNitro() only after ready hook.

Changes to the Nitro instance configuration are not applied.

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

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

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

    nuxt.hook('ready', () => {
      const nitro = useNitro()
      // Do something with Nitro instance
    })
  },
})

Type

function useNitro (): Nitro

`addServerPlugin`

Add plugin to extend Nitro's runtime behavior.

You can read more about Nitro plugins in the Nitro documentation.

It is necessary to explicitly import defineNitroPlugin from nitropack/runtime within your plugin file. The same requirement applies to utilities such as useRuntimeConfig.

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

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

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

Type

function addServerPlugin (plugin: string): void

Параметры

Свойство	Тип	Обязательный	Описание
`plugin`	`string`	да	Путь к плагину. Плагин должен экспортировать функцию по умолчанию, принимающую экземпляр 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('on request', event.path)
  })

  nitroApp.hooks.hook('beforeResponse', (event, { body }) => {
    console.log('on response', event.path, { body })
  })

  nitroApp.hooks.hook('afterResponse', (event, { body }) => {
    console.log('on after response', 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)
    }
  },
})

Type

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

Параметры

Свойство	Type	Required	Description
`routes`	`string \| string[]`	да	Маршрут или массив маршрутов для предварительного рендера.

`addServerImports`

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

Чтобы утилита работала и на сервере, и на клиенте (в т.ч. в 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' }),
    )
  },
})

Type

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

Параметры

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

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

`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'))
  },
})

Type

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

Параметры

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

Примеры

С помощью 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'))
  },
})

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

Функцию useApiSecret можно использовать в серверном коде:

runtime/server/api/hello.ts

const useApiSecret = (): string => ''
// ---cut---
export default defineEventHandler(() => {
  const apiSecret = useApiSecret()
  // Do something with the apiSecret
})

`addServerScanDir`

Add directories to be scanned by Nitro. It will check for subdirectories, which will be registered just like the ~~/server folder is.

Only ~~/server/api, ~~/server/routes, ~~/server/middleware, and ~~/server/utils are scanned.

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

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'))
  },
})

Type

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

Параметры

Свойство	Type	Required	Description
`dirs`	`string \| string[]`	`true`	A directory or an array of directories to register to be scanned for by Nitro as server dirs.
`opts`	`{ prepend?: boolean }`	`false`	Options for the import directory. If `prepend` is `true`, the directory is added to the beginning of the scan list.

Примеры

You can use addServerScanDir to add a directory to be scanned by Nitro. This is useful when you want to add a custom server directory.

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 from server utils!'
}

You can then use the hello function in your server code.

runtime/server/api/hello.ts

function hello () {
  return 'Hello from server utils!'
}
// ---cut---
export default defineEventHandler(() => {
  return hello() // Hello from server utils!
})

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

Report an issue or Edit this page on GitHub

Шаблоны

Nuxt Kit предоставляет набор утилит, которые помогают вам работать с шаблонами. Эти функции позволяют вам генерировать дополнительные файлы во время разработки и сборки.

Resolving

Nuxt Kit предоставляет набор утилит, которые помогут вам разрешать пути. Эти функции позволяют вам разрешать пути, относительные к текущему модулю, с неизвестным именем или расширением.