Nuxt 4とVue 3でフルスタックアプリを構築する:SSR、自動インポート、Nitroサーバーを本番環境まで

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

Nuxt 4が実際に解決すること

Vue 3のカスタム構成(Viteベースなど)を使っていると、どこかで同じ壁にぶつかる。ルーターは動いているが、次はSSRが必要になる。SSRが動いたら今度はAPIレイヤーが必要になる。気づけば3つの関心事を別々に管理している。Nuxt 4はそれを1つにまとめてくれる。

フルスタック開発に踏み込む上で特に重要なのが次の3点だ:

  • サーバーサイドレンダリング(SSR) — ブラウザが何かを受け取る前に、サーバー側でページをレンダリングする。初回表示が速くなり、検索エンジンは空のシェルではなく実際のコンテンツをインデックスできる。設定不要で使い始められる。
  • 自動インポート — Vueのコンポーザブル、コンポーネント、ユーティリティが、import文を1行も書かずにどこでも使える。ファイルがシンプルに保たれ、インポート漏れによるコピペミスもなくなる。
  • Nitroサーバー — SSRと独自APIルートの両方を処理する組み込みサーバーエンジン。server/api/にファイルを置くだけで、NitroがRESTエンドポイントとして公開してくれる。ルーター設定もExpressの設定も不要。

本番環境の2つのサイトでこのスタックを運用したところ、クライアントレンダリングのVue SPAと比較してTTFBが800ms前後から200ms以下に下がった。軽量なデータ取得のためのバックエンドサービスが不要になり、コードベースも小さくなった。

このガイドでは、空のターミナルから本番ビルドを動かすところまでを順を追って説明する。Nuxtの事前知識は不要だ。

インストール

前提条件

Nuxt 4にはNode.js 20以上が必要だ。まずバージョンを確認しよう:

node -v
# v20.x.x以上が表示されればOK

古いバージョンを使っている場合は、nvmを使えば他のプロジェクトに影響を与えずにアップグレードできる:

nvm install 20
nvm use 20

プロジェクトの雛形を作る

公式のNuxt CLIを使えば、Vite、Vue 3、TypeScriptサポート、Nitroサーバーを含むすべてが1コマンドで揃う:

npx nuxi@latest init my-nuxt-app
cd my-nuxt-app
npm install

セットアップウィザードでパッケージマネージャーを選択する。npmとpnpmのどちらでも動く。本番環境ではpnpmへの切り替えを検討する価値がある。同じプロジェクトでnpmと比べてインストールが約2倍速く、node_modulesのディスク使用量も約半分になる。

# 任意:pnpmを使う場合
npm install -g pnpm
pnpm install

プロジェクト構成の概要

生成直後のプロジェクトはこのような構成になっている:

my-nuxt-app/
├── app.vue          # ルートVueコンポーネント
├── nuxt.config.ts   # Nuxtのメイン設定ファイル
├── pages/           # ファイルベースのルーティング
├── components/      # 自動インポートされるVueコンポーネント
├── composables/     # 自動インポートされるコンポーザブル
├── server/
│   └── api/         # NitroのAPIルート
└── public/          # 静的アセット

各フォルダには固有の役割がある。重要なのは、Nuxtがこれらのディレクトリを自動的に読み取るという点だ。ルートは自動登録され、コンポーネントは自動インポートされ、APIエンドポイントはファイルを作成した瞬間に有効になる。

設定

SSRの有効化と調整

SSRはデフォルトで有効になっている。nuxt.config.tsを開いて確認し、基本的なheadメタデータを追加しよう:

// nuxt.config.ts
export default defineNuxtConfig({
  ssr: true,  // デフォルトですでにtrueになっている

  app: {
    head: {
      title: 'My Nuxt App',
      meta: [
        { name: 'description', content: 'Nuxt 4で構築したフルスタックアプリ' }
      ]
    }
  }
})

ログイン後のユーザーダッシュボードなど、SSRが不要なページもある。definePageMetaでルート単位に無効化できる:

// pages/dashboard.vue
<script setup lang="ts">
definePageMeta({
  ssr: false  // クライアントのみでレンダリング
})
</script>

自動インポートの実践

composables/やcomponents/に置いたものはすべてグローバルで使えるようになる。ユーザーデータを取得するコンポーザブルを作ってみよう:

// composables/useUser.ts
export const useUser = () => {
  const user = ref<{ name: string; email: string } | null>(null)

  const fetchUser = async (id: number) => {
    user.value = await $fetch(`/api/users/${id}`)
  }

  return { user, fetchUser }
}

どのページでもインポート文なしで使える:

// pages/profile.vue
<script setup lang="ts">
const { user, fetchUser } = useUser()  // インポート不要

await fetchUser(1)
</script>

<template>
  <div v-if="user">
    <h1>{{ user.name }}</h1>
    <p>{{ user.email }}</p>
  </div>
</template>

Vue 3の組み込み機能も同様に使える。ref、computed、watch、onMounted、どれもNuxtプロジェクト内ではインポート不要だ。これだけでコンポーネントファイルから驚くほどの定型文が削減できる。

NitroでAPIルートを書く

server/api/内のファイルは自動的にHTTPエンドポイントになる。最小限のユーザー検索APIを見てみよう:

// server/api/users/[id].get.ts
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')

  // 実際のデータベース呼び出しに置き換えること
  const users: Record<string, { name: string; email: string }> = {
    '1': { name: 'Alice', email: '[email protected]' },
    '2': { name: 'Bob', email: '[email protected]' }
  }

  const user = users[id as string]

  if (!user) {
    throw createError({ statusCode: 404, message: 'ユーザーが見つかりません' })
  }

  return user
})

ファイル名[id].get.tsには2つの意味がある。[id]が動的ルートパラメータを作り、.getがエンドポイントをGETリクエストのみに限定する。POSTエンドポイントが必要なら、ファイル名を.post.tsにするだけだ。Nitroは追加設定なしでメソッドルーティングを処理してくれる。

実際のデータベースとしては、開発中はSQLiteが便利だ。ドライバをインストールしよう:

npm install better-sqlite3
npm install -D @types/better-sqlite3
// server/utils/db.ts
import Database from 'better-sqlite3'

const db = new Database('./dev.db')

// server/配下のすべてのファイルで自動インポートされる
export { db }

環境変数とランタイム設定

シークレットはソースコードに書くべきではない。Nuxtは.envファイルを読み込み、runtimeConfigを通じて変数をマッピングする:

# .env
NUXT_SECRET_KEY=my-super-secret
NUXT_PUBLIC_API_BASE=https://api.example.com
// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    secretKey: '',       // サーバーのみ(NUXT_SECRET_KEYで上書き)
    public: {
      apiBase: ''        // クライアント+サーバー(NUXT_PUBLIC_API_BASEで上書き)
    }
  }
})

命名規則が重要だ。NUXT_SECRET_KEYはruntimeConfig.secretKeyに、NUXT_PUBLIC_API_BASEはruntimeConfig.public.apiBaseにマッピングされる。Nuxtはプレフィックスに基づいて自動的にマッピングを処理するため、手動でパースする必要はない。サーバールートからアクセスする方法は次の通りだ:

// server/api/protected.get.ts
export default defineEventHandler((event) => {
  const config = useRuntimeConfig(event)
  // config.secretKeyはここで利用可能。クライアントには公開されない
  return { status: 'ok' }
})

動作確認とモニタリング

開発サーバーを起動する

開発サーバーを起動して、ブラウザでhttp://localhost:3000を開こう:

npm run dev

Nuxtは検出したルートをログに出力し、Nitroが動作していることを確認する。正常起動時の表示はこのようになる:

  ➜  Local:    http://localhost:3000/
  ➜  Network:  http://192.168.x.x:3000/
  ✓  Nitro built in 300ms

本番ビルドを作成する

本番ビルドはすべてを単一の.output/ディレクトリにコンパイルする。Nitroはサーバーと静的アセットをまとめてバンドルする:

npm run build

ビルドが完了したら、サーバーを起動する:

node .output/server/index.mjs

実行時にViteも開発用依存関係も不要だ。コンパイルされた出力が通常のNode.jsプロセスとして動くだけだ。

SSRが実際に動作しているか確認する

DevToolsを開いてNetworkタブに移動し、ページをリロードする。メインのHTMLドキュメントのレスポンスをクリックしよう。SSRが有効な場合、レスポンスボディにはJavaScriptが埋めるのを待つ<div id="app"></div>だけでなく、完全にレンダリングされたHTMLが含まれている。

ターミナルからより手早く確認する方法もある:

curl http://localhost:3000/ | grep '<h1'

curlの出力に見出しのテキストが表示されればサーバーレンダリングされている。何も返ってこない場合、そのルートではSSRが機能していない。

Nuxt DevToolsでモニタリングする

Nuxt 4には組み込みのDevToolsパネルが付属している。nuxt.config.tsで有効化しよう:

export default defineNuxtConfig({
  devtools: { enabled: true }
})

開発サーバーを再起動してhttp://localhost:3000にアクセスすると、ページ下部に小さなNuxtアイコンが表示される。クリックするとパネルが開き、以下を確認できる:

  • 検出されたすべてのページとルートパラメータ
  • 自動インポートされたコンポーザブルとコンポーネント
  • Nitroに登録されたサーバーAPIルート
  • ランタイム設定の値(publicのみ)

基本的なヘルスチェックエンドポイント

デプロイ先のプラットフォームが疎通確認できるエンドポイントを用意しよう。最小限のヘルスチェックはこうなる:

// server/api/health.get.ts
export default defineEventHandler(() => {
  return {
    status: 'ok',
    timestamp: new Date().toISOString()
  }
})
curl http://localhost:3000/api/health
# {"status":"ok","timestamp":"2024-..."}

UptimeRobot、Betterstack、またはチームが既に使っているアップタイム監視ツールをこのエンドポイントに向けておこう。ユーザーからの報告で気づくのではなく、サーバーがダウンしてから1分以内にアラートを受け取れるようになる。

次のステップ

ここまでで、高速な初回ロードのためのSSR、コードをクリーンに保つ自動インポート、そしてレンダリングとAPIルートの両方を単一のデプロイで処理するNitroという3つの確固たる基盤が揃った。

次に取り組むとよいことを挙げるとすれば、型安全なデータベースアクセスのためにDrizzle ORMを導入すること(NitroのサーバーユーティリティとスムーズRに統合できる)、nuxt-auth-utilsで認証を追加すること、そしてRailway、Render、またはPM2を動かすVPSへのデプロイだ。いずれも十分にドキュメント化されており、ここで構築したものを大きく作り直す必要はない。

このスタックはPostgreSQLバックエンドと組み合わせて2つのサイトの本番環境で動かしており、合計で月間5万PV以上を処理しているが、アーキテクチャ上の限界には達していない。最初は制約が多く感じるかもしれない。しかし実際に何かをリリースしてみると、フェンスではなくガードレールのように感じられるようになる。

Share: