Nuxt Nation カンファレンスが開催されます。11月12日～13日にご参加ください。
54.8K

server

server/ディレクトリは、アプリケーションにAPIとサーバーハンドラを登録するために使用されます。

Nuxtは、これらのディレクトリ内のファイルを自動的にスキャンして、ホットモジュールリプレースメント（HMR）をサポートするAPIとサーバーハンドラを登録します。

ディレクトリ構造
-| server/
---| api/
-----| hello.ts      # /api/hello
---| routes/
-----| bonjour.ts    # /bonjour
---| middleware/
-----| log.ts        # log all requests

各ファイルは、defineEventHandler()またはeventHandler()（エイリアス）で定義されたデフォルト関数をエクスポートする必要があります。

ハンドラは、JSONデータ、Promiseを直接返すか、event.node.res.end()を使用してレスポンスを送信できます。

server/api/hello.ts
export default 
defineEventHandler
((
event
) => {
  return {
    
hello
: 'world'
  }
})

これで、ページとコンポーネントでこのAPIを普遍的に呼び出すことができます

pages/index.vue
<script setup lang="ts">
const { data } = await useFetch('/api/hello')
</script>

<template>
  <pre>{{ data }}</pre>
</template>

サーバールート

~/server/api 内のファイルは、ルートで自動的に/apiというプレフィックスが付加されます。

/apiプレフィックスなしでサーバールートを追加するには、~/server/routesディレクトリに配置します。

例

server/routes/hello.ts
export default defineEventHandler(() => 'Hello World!')

上記の例では、/helloルートはhttps://127.0.0.1:3000/helloでアクセスできます。

現在、サーバールートはpagesのような動的ルートの全機能をサポートしていないことに注意してください。

サーバミドルウェア

Nuxtは、~/server/middleware内の任意のファイルを自動的に読み取り、プロジェクトのサーバミドルウェアを作成します。

ミドルウェアハンドラは、他のサーバールートの前にすべてのリクエストで実行され、ヘッダーを追加またはチェックしたり、リクエストをログに記録したり、イベントのリクエストオブジェクトを拡張したりします。

ミドルウェアハンドラは、何も返すべきではなく（リクエストを閉じたり、レスポンスしたりすべきではなく）、リクエストコンテキストを検査または拡張するか、エラーをスローするだけです。

サンプル

server/middleware/log.ts
export default defineEventHandler((event) => {
  console.log('New request: ' + getRequestURL(event))
})
server/middleware/auth.ts
export default defineEventHandler((event) => {
  event.context.auth = { user: 123 }
})

サーバープラグイン

Nuxtは~/server/pluginsディレクトリ内のすべてのファイルを自動的に読み込み、Nitroプラグインとして登録します。これにより、Nitroのランタイム動作を拡張し、ライフサイクルイベントにフックすることができます。

例

server/plugins/nitroPlugin.ts
export default defineNitroPlugin((nitroApp) => {
  console.log('Nitro plugin', nitroApp)
})
Nitroプラグインで詳細をご覧ください。

サーバーユーティリティ

サーバールートは、便利なヘルパーセットが付属するunjs/h3によって駆動されます。

利用可能なH3リクエストヘルパーで詳細をご覧ください。

~/server/utilsディレクトリ内に独自のヘルパーを追加できます。

たとえば、元のハンドラをラップし、最終的なレスポンスを返す前に追加の操作を実行するカスタムハンドラユーティリティを定義できます。

例

server/utils/handler.ts
import type { EventHandler, EventHandlerRequest } from 'h3'

export const defineWrappedResponseHandler = <T extends EventHandlerRequest, D> (
  handler: EventHandler<T, D>
): EventHandler<T, D> =>
  defineEventHandler<T>(async event => {
    try {
      // do something before the route handler
      const response = await handler(event)
      // do something after the route handler
      return { response }
    } catch (err) {
      // Error handling
      return { err }
    }
  })

サーバタイプ

この機能はNuxt >= 3.5から利用可能です

'nitro'と'vue'からの自動インポート間のIDE内での明確さを向上させるために、次の内容の~/server/tsconfig.jsonを追加できます

server/tsconfig.json
{
  "extends": "../.nuxt/tsconfig.server.json"
}

現在、これらの値は型チェック（nuxi typecheck）時には考慮されませんが、IDEでより良い型ヒントが得られるはずです。

レシピ

ルートパラメータ

サーバールートは、/api/hello/[name].tsのようにファイル名に括弧で囲まれた動的パラメータを使用でき、event.context.paramsを介してアクセスできます。

server/api/hello/[name].ts
export default defineEventHandler((event) => {
  const name = getRouterParam(event, 'name')

  return `Hello, ${name}!`
})
あるいは、ランタイムと型の安全性を確保するために、Zodなどのスキーマバリデータと共にgetValidatedRouterParamsを使用します。

これで、/api/hello/nuxtでこのAPIを普遍的に呼び出して、Hello, nuxt!を取得できます。

HTTPメソッドのマッチング

ハンドラファイル名には、リクエストのHTTPメソッドと一致させるために、.get、.post、.put、.delete、...などのサフィックスを付けることができます。

server/api/test.get.ts
export default defineEventHandler(() => 'Test get handler')
server/api/test.post.ts
export default defineEventHandler(() => 'Test post handler')

上記の例では、/testを

  • **GET**メソッドでフェッチすると：Test get handlerが返されます
  • **POST**メソッドでフェッチすると：Test post handlerが返されます
  • その他のメソッドでフェッチすると：405エラーが返されます

コードを異なる方法で構造化するために、ディレクトリ内でindex.[method].tsを使用することもできます。これは、API名前空間を作成するのに役立ちます。

export default defineEventHandler((event) => {
  // handle GET requests for the `api/foo` endpoint
})

キャッチオールルート

キャッチオールルートは、フォールバックルートの処理に役立ちます。

例えば、~/server/api/foo/[...].ts という名前のファイルを作成すると、/api/foo/bar/baz のような、ルートハンドラーに一致しないすべてのリクエストをキャッチするルートが登録されます。

server/api/foo/[...].ts
export default defineEventHandler((event) => {
  // event.context.path to get the route path: '/api/foo/bar/baz'
  // event.context.params._ to get the route segment: 'bar/baz'
  return `Default foo handler`
})

キャッチオールルートに名前を設定するには、~/server/api/foo/[...slug].ts を使用し、event.context.params.slug でアクセスします。

server/api/foo/[...slug].ts
export default defineEventHandler((event) => {
  // event.context.params.slug to get the route segment: 'bar/baz'
  return `Default foo handler`
})

ボディ処理

server/api/submit.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  return { body }
})
あるいは、実行時と型の安全性を確保するために、Zod のようなスキーマバリデーターと共に readValidatedBody を使用します。

これで、このAPIを普遍的に呼び出すことができます。

app.vue
<script setup lang="ts">
async function submit() {
  const { body } = await $fetch('/api/submit', {
    method: 'post',
    body: { test: 123 }
  })
}
</script>
ファイル名に submit.post.ts を使用しているのは、リクエストボディを受け入れることができる POST メソッドのリクエストにのみ一致させるためです。GET リクエスト内で readBody を使用すると、readBody は 405 Method Not Allowed HTTP エラーをスローします。

クエリパラメータ

クエリ例 /api/query?foo=bar&baz=qux

server/api/query.get.ts
export default defineEventHandler((event) => {
  const query = getQuery(event)

  return { a: query.foo, b: query.baz }
})
あるいは、実行時と型の安全性を確保するために、Zod のようなスキーマバリデーターと共に getValidatedQuery を使用します。

エラー処理

エラーがスローされない場合、ステータスコード 200 OK が返されます。

キャッチされないエラーは、500 Internal Server Error HTTP エラーを返します。

他のエラーコードを返すには、createError を使用して例外をスローします。

server/api/validation/[id].ts
export default defineEventHandler((event) => {
  const id = parseInt(event.context.params.id) as number

  if (!Number.isInteger(id)) {
    throw createError({
      statusCode: 400,
      statusMessage: 'ID should be an integer',
    })
  }
  return 'All good'
})

ステータスコード

他のステータスコードを返すには、setResponseStatus ユーティリティを使用します。

例えば、202 Accepted を返すには

server/api/validation/[id].ts
export default defineEventHandler((event) => {
  setResponseStatus(event, 202)
})

ランタイム設定

export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig(event)

  const repo = await $fetch('https://api.github.com/repos/nuxt/nuxt', {
    headers: {
      Authorization: `token ${config.githubToken}`
    }
  })

  return repo
})
useRuntimeConfig に引数として event を渡すことはオプションですが、サーバールートの実行時に 環境変数 によって上書きされたランタイム設定を取得するために渡すことをお勧めします。

リクエストクッキー

server/api/cookies.ts
export default defineEventHandler((event) => {
  const cookies = parseCookies(event)

  return { cookies }
})

コンテキストとヘッダーの転送

デフォルトでは、サーバールートでfetchリクエストを行う際、受信リクエストのヘッダーもリクエストコンテキストも転送されません。サーバールートでfetchリクエストを行う際にリクエストコンテキストとヘッダーを転送するには、event.$fetch を使用できます。

server/api/forward.ts
export default defineEventHandler((event) => {
  return event.$fetch('/api/forwarded')
})
**転送されるべきではない**ヘッダーは、リクエストに**含まれません**。これらのヘッダーには、例えば、transfer-encoding、connection、keep-alive、upgrade、expect、host、accept などが含まれます。

高度な使用方法

Nitro設定

nuxt.config の nitro キーを使用して、Nitro設定 を直接設定できます。

これは高度なオプションです。カスタム設定は本番環境のデプロイメントに影響を与える可能性があります。NitroがNuxtのsemver-minorバージョンでアップグレードされた場合、設定インターフェースが時間の経過とともに変更される可能性があるためです。
nuxt.config.ts
export default defineNuxtConfig({
  // https://nitro.unjs.io/config
  nitro: {}
})
詳しくは**ドキュメント > ガイド > コンセプト > サーバーエンジン**をご覧ください。

ネストされたルーター

server/api/hello/[...slug].ts
import { createRouter, defineEventHandler, useBase } from 'h3'

const router = createRouter()

router.get('/test', defineEventHandler(() => 'Hello World'))

export default useBase('/api/hello', router.handler)

ストリームの送信

これは実験的な機能であり、すべての環境で利用できます。
server/api/foo.get.ts
import fs from 'node:fs'
import { sendStream } from 'h3'

export default defineEventHandler((event) => {
  return sendStream(event, fs.createReadStream('/path/to/file'))
})

リダイレクトの送信

server/api/foo.get.ts
export default defineEventHandler(async (event) => {
  await sendRedirect(event, '/path/redirect/to', 302)
})

レガシーハンドラーまたはミドルウェア

server/api/legacy.ts
export default fromNodeMiddleware((req, res) => {
  res.end('Legacy handler')
})
unjs/h3 を使用すればレガシーサポートは可能ですが、可能な限りレガシーハンドラーは避けることをお勧めします。
server/middleware/legacy.ts
export default fromNodeMiddleware((req, res, next) => {
  console.log('Legacy middleware')
  next()
})
next() コールバックと async であるか Promise を返すレガシーミドルウェアを組み合わせて使用しないでください。

サーバーストレージ

Nitro はクロスプラットフォームの ストレージレイヤー を提供します. 追加のストレージマウントポイントを設定するには、nitro.storage または サーバープラグイン を使用できます。

Redisストレージを追加する例

nitro.storage を使用する場合

nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    storage: {
      redis: {
        driver: 'redis',
        /* redis connector options */
        port: 6379, // Redis port
        host: "127.0.0.1", // Redis host
        username: "", // needs Redis >= 6
        password: "",
        db: 0, // Defaults to 0
        tls: {} // tls/ssl
      }
    }
  }
})

次に、API ハンドラーで

server/api/storage/test.ts
export default defineEventHandler(async (event) => {
  // List all keys with
  const keys = await useStorage('redis').getKeys()

  // Set a key with
  await useStorage('redis').setItem('foo', 'bar')

  // Remove a key with
  await useStorage('redis').removeItem('foo')

  return {}
})
Nitroストレージレイヤーの詳細をご覧ください。

あるいは、サーバープラグインとランタイム設定を使用してストレージマウントポイントを作成することもできます。

import redisDriver from 'unstorage/drivers/redis'

export default defineNitroPlugin(() => {
  const storage = useStorage()

  // Dynamically pass in credentials from runtime configuration, or other sources
  const driver = redisDriver({
      base: 'redis',
      host: useRuntimeConfig().redis.host,
      port: useRuntimeConfig().redis.port,
      /* other redis connector options */
    })

  // Mount driver
  storage.mount('redis', driver)
})

public

public/ディレクトリは、Webサイトの静的アセットを提供するために使用されます。

utils

utils/ディレクトリを使用して、アプリケーション全体でユーティリティ関数を自動インポートします。