本文へ移動
← Archive No.07 / 15 Svelte →
Svelte

SvelteKit 3 × microCMS:+page.server.tsとprerenderで記事ページを生成する

Svelte

「Svelte Base」は SvelteKit と microCMS で作ったサイトです。記事一覧と記事ページは +page.server.ts でデータを取得し、prerender でビルド時に HTML を生成しています。SvelteKit 3 に上げたので、設定ファイル・環境変数・import の書き方が変わった点もあわせて紹介します。

リポジトリ:SvelteKit-TypeScript-MicroCMS-Site / デモ:https://sveltebase-phi.vercel.app/

SvelteKit 3 で変わったところ

  • 設定は svelte.config.js ではなく、vite.config.ts の sveltekit() に書く
  • 環境変数は src/env.ts で宣言し、$app/env/private から読む($env/* は非推奨)
  • $lib のエイリアスが無くなったので、package.json の imports で #lib を用意する
  • tsconfig.json は $app/tsconfig を継承する

設定は vite.config.ts にまとめる

アダプターの指定も Vite の設定に入ったので、svelte.config.js は削除しました。

ts
// vite.config.ts
import adapter from '@sveltejs/adapter-vercel';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    sveltekit({
      adapter: adapter({ runtime: 'nodejs24.x' })
    })
  ]
});
json
// tsconfig.json
{
  "extends": "$app/tsconfig",
  "compilerOptions": { "strict": true }
}

API キーは src/env.ts で宣言する

SvelteKit 3 では、使う環境変数を src/env.ts の defineEnvVars で宣言します。宣言した変数は $app/env/private から import でき、既定でサーバー専用です。ブラウザで動くコードから import するとビルドエラーになるので、キーの漏れを仕組みで防げます。

ts
// src/env.ts
import { defineEnvVars } from '@sveltejs/kit/env';

export const variables = defineEnvVars({
  MICROCMS_SERVICE_DOMAIN: {
    description: 'microCMS service domain (the `xxx` in xxx.microcms.io)'
  },
  MICROCMS_API_KEY: {
    description: 'microCMS API key'
  }
});

description を書いておくと、エディタで変数にカーソルを合わせたときに説明が出ます。以前は $env/static/private と $env/dynamic/private を使い分けていましたが、どちらも $app/env/private にまとまりました。

ts
// src/lib/microcms.ts
import { createClient, type MicroCMSQueries } from 'microcms-js-sdk';
import { MICROCMS_SERVICE_DOMAIN, MICROCMS_API_KEY } from '$app/env/private';

const client = createClient({ serviceDomain: MICROCMS_SERVICE_DOMAIN, apiKey: MICROCMS_API_KEY });

export const getList = async (queries?: MicroCMSQueries) =>
  await client.get<BlogResponse>({ endpoint: 'blogs', queries });

export const getDetail = async (contentId: string, queries?: MicroCMSQueries) =>
  await client.getListDetail<Blog>({ endpoint: 'blogs', contentId, queries });

一覧ページ

microCMS のリスト API は、何も指定しないと 10 件しか返しません。同じ microCMS には Astro や Next.js など他のフレームワークの記事も入っているので、limit: 100 でまとめて取得し、ページ側で Svelte の記事に絞っています。

ts
// src/routes/+page.server.ts
export const load: PageServerLoad = async () => {
  return await getList({ limit: 100 });
};
export const prerender = true;
svelte
<!-- src/routes/+page.svelte -->
<script lang="ts">
  import type { PageData } from './$types';
  let { data }: { data: PageData } = $props();

  // カテゴリが Svelte の記事を新しい順に 3 件
  const posts = $derived(data.contents.filter((c) => c.category?.name === 'Svelte').slice(0, 3));
</script>

記事ページと 404

存在しない ID を開いたときに 500 にならないよう、SDK が投げる 404 のエラーを SvelteKit の error(404) に変換しています。error() は関数の中で例外を投げてくれるので、throw は書きません。

ts
// src/routes/[slug]/+page.server.ts
import { error } from '@sveltejs/kit';

export const load: PageServerLoad = async ({ params }) => {
  try {
    return await getDetail(params.slug);
  } catch (err) {
    // microcms-js-sdk は "fetch API response status: 404" のような Error を投げる
    if (err instanceof Error && /status: 404/.test(err.message)) {
      error(404, 'Not Found');
    }
    throw err;
  }
};
export const prerender = true;

prerender の対象はどう決まる?

[slug] のような動的ルートでも、prerender 時に SvelteKit がトップページからリンクをたどって対象のページを見つけてくれます。トップのヒーローとブログ欄から各記事にリンクしているので、entries を書かなくても記事ページが生成されます。トップに出ない記事まで生成したい場合は、entries で ID の一覧を返します。

$lib の代わりに #lib

SvelteKit 3 では $lib のエイリアスが無くなりました。代わりに Node.js の標準の仕組みである package.json の imports(サブパスインポート)を使います。# から始まる名前にする決まりです。

json
// package.json
{
  "imports": {
    "#lib": "./src/lib",
    "#lib/*": "./src/lib/*"
  }
}
ts
import { formatDate } from '#lib/format.ts';
import type { Blog } from '#lib/microcms.ts';

#lib/* はファイル名にそのまま置き換わるので、.ts の拡張子まで書きます。

アイキャッチは WebP で

microCMS の画像は URL パラメータで変換できるので、?w=1600&fm=webp を付けて軽くしています。width/height に MicroCMSImage の値を渡しておくと、読み込み時のレイアウトのずれも防げます。日付は dayjs で 2026.11.14 の形にそろえています。

svelte
<time datetime={data.publishedAt}>{formatDate(data.publishedAt)}</time>
<h1 class="article__title">{data.title}</h1>
{#if data.eyecatch}
  <img src="{data.eyecatch.url}?w=1600&fm=webp" alt=""
       width={data.eyecatch.width} height={data.eyecatch.height} />
{/if}
<div class="article__body">{@html data.content}</div>

まとめ

  • 設定は vite.config.ts の sveltekit() に書く
  • キーは src/env.ts で宣言し、$app/env/private から読む
  • +page.server.ts と prerender = true で静的生成。一覧は limit を指定する
  • SDK の 404 は error(404) に変換
  • $lib の代わりに #lib のサブパスインポート