Nitro

Nuxt Kit은 Nitro와 함께 작업할 수 있도록 도와주는 유틸리티 집합을 제공합니다. 이 함수들을 사용하여 서버 핸들러, 플러그인, 프리렌더 라우트를 추가할 수 있습니다.

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

`addServerHandler`

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

사용법

import { createResolver, defineNuxtModule, addServerHandler } 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`	`boolean`	`false`	이 핸들러가 미들웨어임을 지정합니다. 미들웨어는 모든 라우트에서 호출되며, 다음 핸들러로 넘기기 위해 보통 아무것도 반환하지 않아야 합니다.
`lazy`	`boolean`	`false`	핸들러를 지연 로딩하여 import합니다. 필요할 때만 핸들러를 로드하고 싶을 때 유용합니다.
`method`	`string`	`false`	라우터 메서드 매처. 핸들러 이름에 메서드명이 포함되어 있으면 기본값으로 사용됩니다.

예시

기본 사용법

addServerHandler를 사용하여 모듈에서 서버 핸들러를 추가할 수 있습니다.

import { createResolver, defineNuxtModule, addServerHandler } 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 { createResolver, defineNuxtModule, addDevServerHandler } from '@nuxt/kit'

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

타입

function addDevServerHandler (handler: NitroDevEventHandler): void

파라미터

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

속성	타입	필수	설명
`handler`	`EventHandler`	`true`	이벤트 핸들러.
`route`	`string`	`false`	경로 접두사 또는 라우트. 빈 문자열을 사용하면 미들웨어로 사용됩니다.

예시

기본 사용법

경우에 따라 개발 전용 서버 핸들러(예: Tailwind config viewer)를 만들고 싶을 수 있습니다.

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

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

    // @ts-ignore
    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의 런타임 동작을 확장하는 플러그인을 추가합니다.

Nitro 플러그인에 대한 자세한 내용은 Nitro 문서에서 확인할 수 있습니다.

사용법

import { createResolver, defineNuxtModule, addServerPlugin } 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`	플러그인 경로. 플러그인은 Nitro 인스턴스를 인자로 받는 기본 함수를 export해야 합니다.

예시

import { createResolver, defineNuxtModule, addServerPlugin } 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 { defineNuxtModule, addPrerenderRoutes } 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`	프리렌더링할 라우트 또는 라우트 배열.

`addServerImportsDir`

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

사용법

import { defineNuxtModule, createResolver, addServerImportsDir } 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`	import 디렉토리 옵션. `prepend`가 `true`면 디렉토리가 스캔 리스트의 앞에 추가됩니다.

예시

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

import { defineNuxtModule, createResolver, addServerImportsDir } 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

export default defineEventHandler(() => {
  const apiSecret = useApiSecret()
  // apiSecret으로 무언가를 수행
})

`addServerScanDir`

Nitro가 스캔할 디렉토리를 추가합니다. 하위 디렉토리도 확인하며, ~/server 폴더와 동일하게 등록됩니다.

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

사용법

import { defineNuxtModule, createResolver, addServerScanDir } 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`	Nitro가 서버 디렉토리로 스캔할 디렉토리 또는 디렉토리 배열.
`opts`	`{ prepend?: boolean }`	`false`	import 디렉토리 옵션. `prepend`가 `true`면 디렉토리가 스캔 리스트의 앞에 추가됩니다.

예시

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

import { defineNuxtModule, createResolver, addServerScanDir } 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!'
}

이제 서버 코드에서 hello 함수를 사용할 수 있습니다.

runtime/server/api/hello.ts

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