Nitro

Source
Nuxt Kit은 Nitro로 작업하는 데 도움이 되는 유틸리티 세트를 제공합니다. 이 함수들을 사용하면 서버 핸들러, 플러그인 및 프리렌더 라우트를 추가할 수 있습니다.

Nitro는 초고속 웹 서버를 구축하기 위한 오픈 소스 TypeScript 프레임워크입니다. Nuxt는 Nitro를 서버 엔진으로 사용합니다. useNitro를 사용해 Nitro 인스턴스에 접근할 수 있고, addServerHandler로 서버 핸들러를 추가할 수 있으며, addDevServerHandler로 개발 모드에서만 사용되는 서버 핸들러를 추가할 수 있습니다. 또한 addServerPlugin으로 Nitro의 런타임 동작을 확장하는 플러그인을 추가하고, addPrerenderRoutes로 Nitro가 프리렌더할 라우트를 추가할 수 있습니다.

addServerHandler

Nitro 서버 핸들러를 추가합니다. 서버 미들웨어나 커스텀 라우트를 만들고 싶을 때 사용하세요.

Usage

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

Type

function addServerHandler (handler: NitroEventHandler): void

Parameters

handler: 다음 속성을 가진 핸들러 객체:

PropertyTypeRequiredDescription
handlerstringtrue이벤트 핸들러의 경로.
routestringfalse경로 프리픽스 또는 라우트. 빈 문자열을 사용하면 미들웨어로 사용됩니다.
middlewarebooleanfalse이 핸들러가 미들웨어인지 지정합니다. 미들웨어는 모든 라우트에서 호출되며, 일반적으로 다음 핸들러로 넘기기 위해 아무것도 반환하지 않아야 합니다.
lazybooleanfalse핸들러를 가져올 때 지연 로딩을 사용합니다. 이는 핸들러를 필요할 때만 로드하고 싶을 때 유용합니다.
methodstringfalse라우터 메서드 매처. 핸들러 이름에 메서드 이름이 포함되어 있으면 기본값으로 사용됩니다.

Examples

Basic Usage

모듈에서 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'),
    })
  },
})

/robots.txt에 접근하면 다음과 같은 응답을 반환합니다:

User-agent: *
Disallow: /

addDevServerHandler

개발 모드에서만 사용되는 Nitro 서버 핸들러를 추가합니다. 이 핸들러는 프로덕션 빌드에서는 제외됩니다.

Usage

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

Type

function addDevServerHandler (handler: NitroDevEventHandler): void

Parameters

handler: 다음 속성을 가진 핸들러 객체:

PropertyTypeRequiredDescription
handlerEventHandlertrue이벤트 핸들러.
routestringfalse경로 프리픽스 또는 라우트. 빈 문자열을 사용하면 미들웨어로 사용됩니다.

Examples

Basic Usage

일부 경우에는 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는 올바른 타입을 제공하지 않습니다
    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 인스턴스를 반환합니다.

ready 훅 이후에만 useNitro()를 호출할 수 있습니다.
Nitro 인스턴스 설정에 대한 변경 사항은 적용되지 않습니다.

Usage

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 인스턴스로 무언가를 수행
    })
  },
})

Type

function useNitro (): Nitro

addServerPlugin

Nitro의 런타임 동작을 확장하기 위한 플러그인을 추가합니다.

Nitro 플러그인에 대해 더 알고 싶다면 Nitro 문서를 참고하세요.
플러그인 파일 내에서 defineNitroPlugin을 nitropack/runtime에서 명시적으로 import해야 합니다. useRuntimeConfig와 같은 유틸리티에도 동일한 요구 사항이 적용됩니다.

Usage

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

Parameters

PropertyTypeRequiredDescription
pluginstringtrue플러그인의 경로. 플러그인은 Nitro 인스턴스를 인자로 받는 기본 함수를 export해야 합니다.

Examples

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

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

addPrerenderRoutes

Nitro에 프리렌더할 라우트를 추가합니다.

Usage

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

Parameters

PropertyTypeRequiredDescription
routesstring | string[]true프리렌더할 라우트 또는 라우트 배열.

addServerImports

서버에 import를 추가합니다. 이를 통해 Nitro에서 수동으로 import하지 않고도 해당 import를 사용할 수 있습니다.

Usage

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

Parameters

imports: 다음 속성을 가진 객체 또는 객체 배열:

PropertyTypeRequiredDescription
namestringtrue감지할 import 이름.
fromstringtrueimport할 모듈 식별자.
prioritynumberfalseimport의 우선순위; 동일한 이름의 import가 여러 개 있을 경우, 가장 높은 우선순위를 가진 것이 사용됩니다.
disabledbooleanfalse이 import가 비활성화되었는지 여부.
metaRecord<string, any>falseimport의 메타데이터.
typebooleanfalse이 import가 순수 타입 import인지 여부.
typeFromstringfalse타입 선언을 생성할 때 from 값으로 사용할 값.
asstringfalse이 이름으로 import.

addServerImportsDir

Nitro가 자동 import를 위해 스캔할 디렉터리를 추가합니다.

Usage

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

Parameters

PropertyTypeRequiredDescription
dirsstring | string[]trueNitro가 스캔하도록 등록할 디렉터리 또는 디렉터리 배열.
opts{ prepend?: boolean }falseimport 디렉터리에 대한 옵션. prepend가 true이면, 디렉터리가 스캔 목록의 시작 부분에 추가됩니다.

Examples

addServerImportsDir를 사용해 Nitro가 스캔할 디렉터리를 추가할 수 있습니다. 이는 Nitro가 커스텀 서버 디렉터리에서 함수를 자동 import하도록 하고 싶을 때 유용합니다.

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

그런 다음 서버 코드에서 useApiSecret 함수를 사용할 수 있습니다:

runtime/server/api/hello.ts
export default defineEventHandler(() => {
  const apiSecret = useApiSecret()
  // apiSecret으로 무언가를 수행
})

addServerScanDir

Nitro가 스캔할 디렉터리를 추가합니다. 하위 디렉터리를 확인하여 ~/server 폴더와 동일한 방식으로 등록합니다.

~/server/api, ~/server/routes, ~/server/middleware, ~/server/utils만 스캔됩니다.

Usage

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

Parameters

PropertyTypeRequiredDescription
dirsstring | string[]trueNitro가 서버 디렉터리로 스캔하도록 등록할 디렉터리 또는 디렉터리 배열.
opts{ prepend?: boolean }falseimport 디렉터리에 대한 옵션. prepend가 true이면, 디렉터리가 스캔 목록의 시작 부분에 추가됩니다.

Examples

addServerScanDir를 사용해 Nitro가 스캔할 디렉터리를 추가할 수 있습니다. 이는 커스텀 서버 디렉터리를 추가하고 싶을 때 유용합니다.

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

그런 다음 서버 코드에서 hello 함수를 사용할 수 있습니다.

runtime/server/api/hello.ts
export default defineEventHandler(() => {
  return hello() // Hello from server utils!
})