SvelteKit(+pnpm)でGitHub Pagesホスティング(+カスタムドメイン)
SvelteKit(+pnpm)で作成したWebアプリケーションをGitHub Pagesにホスティング（＋カスタムドメイン構成）する際のノウハウメモです（2025年1月現在）。
SvelteKitで作成したWebアプリケーションを静的サイト生成（SSG: Static Site Generation）する際の情報になります。
以前の記事「Next.js 14(+pnpm)でGitHub Pagesホスティング(+カスタムドメイン)」のSvelteKit版です。以下の手順は、GitHub Pagesでカスタムドメイン適用（サーバルート＝アプリケーションルート：https://example.com/）でも、非適用（サーバルート≠アプリケーションルート：https://example-user.github.io/repository-name/）でも、同じ方法で問題ありません。
公式ドキュメント（2025年1月参照時）にほとんど書いてある内容ではあります。
必要パッケージの導入
以下のコマンドでプロジェクトに静的サイト生成のためのパッケージを導入しておきます。
pnpm install --dev @sveltejs/adapter-static開発資産の修正点
src/routes/layout.js
export const prerender = true;src/routes/*/+page.svelte（など）
$apps/pathsからbaseをインポートし、baseでa要素やimg要素のURLをプレフィクス修飾します。
<script>
import { base } from '$app/paths';
</script>
<a href="{base}/example">/example</a>
<img src="{base}/example.png" alt="example" />修正しないとGitHub Actionsでのビルド時に失敗します。なおexport const trailingSlash = 'always'により末尾スラッシュを常に付加して相対パスを利用する場合は修飾不要です（以下は2つ上位の親階層へのルーティング）。
<a href="../..">../..</a>svelte.config.js
import adapter from '@sveltejs/adapter-static';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
/** @type {import('@sveltejs/kit').Config} */
const config = {
// Consult https://svelte.dev/docs/kit/integrations
// for more information about preprocessors
preprocess: vitePreprocess(),
kit: {
adapter: adapter({
pages: 'build',
assets: 'build',
fallback: '404.html',
precompress: false,
strict: true
}),
paths: {
base: process.argv.includes('dev') ? '' : process.env.BASE_PATH
}
}
};
export default config;SvelteKitプロジェクト作成時のデフォルトから変更している部分をハイライトしています。
adapterインポート元パッケージをadapter-autoからadapter-staticに変更- 前掲の手順で導入しているパッケージに置き換えます。
config.kit内を設定- デフォルトでは
adapter: dapter()になっていると思いますが、公式ドキュメントに示されている内容に置き換えます。 - 公式ドキュメントでは最初に一般的な設定が記述され、ドキュメントの後の方でGitHub Pagesに特化した記述がされており、上記はそれらを統合したものになります。
- デフォルトでは
GitHub Actionsの構成
開発資産をGitHubリポジトリにpushした際に静的サイトが生成されるようにGitHub Actionsを構成します。内容（特にアクションやNodeのバージョンなど）は時期により異なりますので、状況に応じて適宜対応する必要があります。以下の記述は2025年1月実施時点での内容になります。
SvelteKitに関してはGitHubでテンプレートが用意されていないので（見落としていたらすみません）、定義ファイルを1から作成することになります。
- 通常のリポジトリ内ファイルとしてローカル環境でテキストエディタ等で作成してコミットし、GitHubリポジトリにpush
- GitHub画面で作成して直接GitHubリポジトリにコミット
リポジトリ内ディレクトリ/.github/workflows/配下に配置していればファイル名は任意で、内容が妥当であればGitHubによって有効なActions定義として処理されます。拡張子は.ymlが妥当でしょう。
以下はGitHub画面で作成する際の編集画面までのたどり方を示しますが、ローカル環境でテキストエディタ等で作成する場合はスキップしてください。
GitHub画面でのActions作成手順
GitHubリポジトリページ > Settings > Code and automation > Pages
GitHub Pages > Build and deployment > Source
プルダウンからGitHub Actionsを選択
"create your own"のリンクを選択。
その後テキストエディタ画面が表示されますので、エディタの上側にある"<リポジトリ名>/.github/workflows/"の右隣の入力欄に任意のファイル名.ymlを指定したり、テキストエディタ入力欄を後述の内容ですべて置き換えて画面右上の"Commit changes..."ボタンを選択してリポジトリにコミットできます。
GitHub Actions定義ファイルの内容
ローカル環境でも、GitHub画面でもGitHub Actions定義ファイルの内容として以下を指定します。
name: Deploy to GitHub Pages
on:
push:
branches: 'main'
jobs:
build_site:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
# If you're using pnpm, add this step then change the commands and cache key below to use `pnpm`
- name: Install pnpm
uses: pnpm/action-setup@v3
with:
version: 8
- name: Install Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: pnpm
- name: Install dependencies
run: pnpm install
- name: build
env:
BASE_PATH: '/${{ github.event.repository.name }}'
run: |
pnpm run build
- name: Upload Artifacts
uses: actions/upload-pages-artifact@v3
with:
# this should match the `pages` option in your adapter-static options
path: 'build/'
deploy:
needs: build_site
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy
id: deployment
uses: actions/deploy-pages@v4これも公式ドキュメントに示されている内容をベースとしています。改行やインデントの補正の他、ハイライトで示している以下の変更をしています。pnpmを利用するのでなければ以下の修正は不要になります。
- pnpm利用
- YAML記述の階層
/jobs/build_site/steps配下で以下の変更name: Install pnpm- セクション全体のコメントアウトを解除して有効化
name: Install Node.jswith/cacheのnpmをpnpmに変更
name: Install dependenciesrunのnpm installをpnpm installに変更
name: buildrunのnpm run buildをpnpm run buildに変更
- YAML記述の階層
また公式ドキュメントにも記載されていますように、リポジトリの最上位ディレクトリに.nojekyllというファイル（中身は空）を配置することにより、GitHub Pagesによる想定外の不具合を未然に防げる場合もあるかと思います。
GitHub Actionsの実行確認方法
mainブランチにpushするとActionsが実行されてビルド（静的サイト生成）が実施されます。
実行状況はリポジトリの”Actions“メニューで確認できます。
カスタムドメインの設定を行う前や、カスタムドメインの設定を行わない場合では、”https://<GitHubアカウント名>.github.io/<リポジトリ名>/“へアクセスすることにより生成された内容を参照することができます。
カスタムドメインの構成
生成した静的サイトをgithub.ioではなくカスタムドメインにする場合の方法の説明になります。以下でGitHub設定を行う前にDNS設定を行うと、第三者によるドメインの乗っ取りが行われるタイミングが生じる（サブドメインテイクオーバー）ケースがあるため御注意ください。
カスタムドメインのためのGitHub設定
GitHubリポジトリページ > Settings > Code and automation > Pages
Build and deployment > Custom domain
入力欄にカスタムドメインを指定して”Save“ボタンを選択します。直後にDNSチェックが走り、少しするとエラー表示がされます。
カスタムドメインのためのDNS設定
カスタムドメインがGitHub Pages（github.io）を指すようにDNS CNAMEレコードを構成します（以下DNSレコード設定のイメージ）。
<カスタムドメイン> CNAME <GitHubアカウント名>.github.ioDNS設定後のカスタムドメインのためのGitHub設定
DNS設定を行った後、GitHub設定に戻りCustom domainの”Check again“ボタンをクリックします。DNS設定の認識状況によりますので、時間の経過後のリトライが必要になる場合もあります。Check結果がOKになりますと、元のhttps://<GitHubアカウント名>.github.io/<リポジトリ名>/へのアクセスもカスタムドメインへリダイレクトされるようになります。
HTTPS強制化
カスタムドメイン設定後、サーバ証明書が発行されるまで時間がかかりますので、”Enforce HTTPS“のチェックボックスが有効（クリック可能）になるまで待ち、有効化されたらチェックしてHTTPS強制化を行います。チェック後Custom domainでの表示が”DNS Check in Progress“にまたしばらくなるようです。
その他参考情報
Visual Studio Codeでのデバッグ（ステップ実行等）
.vscode/launch.jsonに以下の記述をすることにより、ローカル（localhost:5173）でのWebブラウザアクセス起点によるデバッグ実行ができ、VSCode上のブレークポイント設定やステップ実行、変数値参照等が行えます。ただし自分が試した限りでは拡張子.jsのソースでは問題ありませんでしたが、+page.svelteファイルの<script>内ではブレークポイントが設定できなかったり、設定できても実行時に他の行に設定されるという挙動があり、記事作成時点では解決できていません。
{
"version": "0.2.0",
"configurations": [
{
"name": "SvelteKit debug",
"type": "node-terminal",
"request": "launch",
"command": "pnpm run dev"
}
]
}Visual Studio CodeではSvelte for VSCode拡張機能などを導入するのもよいでしょう。
主な参考情報
- Next.js 14(+pnpm)でGitHub Pagesホスティング(+カスタムドメイン)
- Static site generation • Docs • Svelte
- Breakpoint Debugging • Docs • Svelte
Comments
Join the conversation on Bluesky
リプライテスト
autoblueテスト
リプライテスト