Nuxt 4 × microCMS:APIキーをブラウザに出さないServer API構成

Nuxt 4 と microCMS で作ったポートフォリオサイト「Nuxt Base」では、microCMS の API キーをブラウザに一切渡さない構成にしています。ページから直接 microCMS を呼ぶのではなく、Nuxt の Server API(server/api)を間に挟む方法です。Nuxt 3 から Nuxt 4 に上げたときに、ディレクトリ構成と型の置き場所も見直しました。

リポジトリ:Nuxtjs-TypeScript-Gsap-MicroCMS-Site / デモ:https://nuxtbase-gsap.vercel.app/

なぜ Server API を挟むのか

microcms-js-sdk をページの <script setup> で使うと、クライアント側のナビゲーションでもリクエストが走るため、API キーがバンドルに含まれてしまいます。読み取り専用のキーでも、下書きの取得権限などを付けていると漏れたときの影響が大きくなります。そこで、キーはサーバーだけが持ち、ページは自前の /api/blogs を叩く形にしました。

Nuxt 4 のディレクトリ構成

Nuxt 4 では、画面側のコードを app/ の下にまとめる構成が標準になりました。サーバー側の server/ と、両方から使う shared/ を分けて置きます。

app/        ページ・コンポーネント・プラグインなど(ブラウザでも動く)
server/     Server API とサーバー専用の処理
shared/     画面とサーバーの両方で使う型

画面とサーバーの境目がフォルダで分かれるので、「API キーを触るコードは server/ の中だけ」というルールが守りやすくなります。

runtimeConfig にキーを置く

runtimeConfig の直下(public の外)に置いた値は、サーバー側でしか参照できません。

// nuxt.config.ts
export default defineNuxtConfig({
  compatibilityDate: '2026-11-21',
  runtimeConfig: {
    // サーバー側のみで使用(クライアントには公開しない)
    microcms: {
      serviceDomain: process.env.MICROCMS_SERVICE_DOMAIN,
      apiKey: process.env.MICROCMS_API_KEY
    }
  }
})

クライアントの生成は server/utils に置くと、Server API から自動インポートで使えます。

// server/utils/microcms.ts
import { createClient } from 'microcms-js-sdk'

export const useMicroCMSClient = () => {
  const config = useRuntimeConfig()
  return createClient({
    serviceDomain: config.microcms.serviceDomain,
    apiKey: config.microcms.apiKey
  })
}

型は shared/ に置いて、画面とサーバーで共有する

記事の型は shared/types/article.ts に置きました。Nuxt 4 では、#shared というエイリアスで画面からもサーバーからも同じファイルを読み込めます。以前は types/ に置いていましたが、型を二重に書いたり、片方だけ直し忘れたりする心配がなくなりました。

// shared/types/article.ts
import type { MicroCMSImage } from 'microcms-js-sdk'

export interface Article {
  id: string
  publishedAt: string
  title: string
  content: string
  eyecatch?: MicroCMSImage
  category: { name: string }
}

一覧と詳細のエンドポイント

一覧では本文(content)を返さないよう fields で絞っています。トップページで記事カードを並べるだけなら、本文は不要なうえにレスポンスが重くなるためです。

// server/api/blogs/index.get.ts
import type { ArticleResponse } from '#shared/types/article'

export default defineEventHandler(async () => {
  const client = useMicroCMSClient()
  return await client.get<ArticleResponse>({
    endpoint: 'blogs',
    queries: { fields: ['id', 'title', 'eyecatch', 'category', 'publishedAt'], limit: 100 }
  })
})

詳細のエンドポイントでは、存在しない ID のときに 404 をそのまま返すのがポイントです。microcms-js-sdk は 404 のときに fetch API response status: 404 というメッセージの Error を投げるので、それを見て createError に変換します。こうしないと、存在しない記事の URL が 500 エラーになってしまいます。

// server/api/blogs/[id].get.ts
import type { Article } from '#shared/types/article'

export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')
  if (!id) throw createError({ statusCode: 400, statusMessage: 'Missing id' })
  try {
    return await useMicroCMSClient().getListDetail<Article>({ endpoint: 'blogs', contentId: id })
  } catch (err) {
    if (err instanceof Error && /status: 404/.test(err.message)) {
      throw createError({ statusCode: 404, statusMessage: 'Article not found' })
    }
    throw err
  }
})

ページ側は useFetch で呼ぶだけ

// app/pages/articles/[slug].vue
const { data, error } = await useFetch<Article>(`/api/blogs/${slug}`, { key: `article-${slug}` })
if (error.value) {
  throw createError({ statusCode: error.value.statusCode ?? 500, fatal: true })
}

useSeoMeta({
  title: `${data.value?.title} | Nuxt Base`,
  description: data.value?.title
})

fatal: true を付けると、クライアント遷移時でも error.vue のエラーページに切り替わります。タイトルや説明文は useHead の meta 配列ではなく、useSeoMeta で書くようにしました。ogTitle などのキー名に型が付くので、書き間違いに気づけます。

一覧ページでは、取得した結果を computed で受け取っています。

// app/pages/blog.vue
const { data } = await useFetch<ArticleResponse>('/api/blogs', { key: 'articles' })
const articles = computed(() => data.value?.contents ?? [])

以前は const articles = data.value?.contents ?? [] と書いていましたが、これだと取得した瞬間の値をコピーするだけなので、データを取得し直しても表示が変わりません。computed にしておけば、data が更新されたときに一覧も追従します。

まとめ

  • API キーは runtimeConfig の非公開領域に置く
  • microCMS へのアクセスは server/api に閉じ込める
  • 型は shared/ に置き、#shared で画面とサーバーから共有する
  • 一覧は fields で必要な項目だけ返す
  • SDK の 404 を createError で 404 に変換する
  • useFetch の結果は computed で受け取り、メタ情報は useSeoMeta で書く