Sveltia CMS スキル
静的サイトプロジェクトにSveltia CMSを統合するための完全なスキルです。
Sveltia CMSとは?
Sveltia CMS は、Gitベースの軽量ヘッドレスコンテンツ管理システムであり、Decap CMS(旧Netlify CMS)のモダンな後継としてゼロから構築されました。Gitリポジトリに保存されたコンテンツに対して、高速で直感的な編集インターフェースを提供します。
主な特徴
-
軽量&高速
- バンドルサイズ: <500 KB(minified/brotlied) vs 競合の1.5-2.6 MB
- Svelteコンパイラで構築(仮想DOMオーバーヘッドなし)
- GraphQL APIによるインスタントなコンテンツ取得
- 全コンテンツに対する関連性ベースの検索
-
モダンなユーザーエクスペリエンス
- ビューポートを最大限に活用した直感的な管理画面
- ダークモード対応(システム設定に追従)
- モバイル・タブレット最適化
- 複数ファイル対応のドラッグ&ドロップアップロード
- インスタント更新によるリアルタイムプレビュー
-
Gitネイティブアーキテクチャ
- コンテンツはMarkdown、MDX、YAML、TOML、JSONとして保存
- 完全なバージョン管理と変更履歴
- ベンダーロックインなし - コンテンツはコードとともに
- GitHub、GitLab、Gitea、Forgejoバックエンド対応
-
フレームワーク非依存
- バニラJavaScriptバンドルとして提供
- Hugo、Jekyll、11ty、Gatsby、Astro、Next.js、SvelteKitで動作
- React、Vue、その他のフレームワークランタイム依存なし
- あらゆる静的サイトジェネレーターと互換性
-
ファーストクラスの国際化対応
- 複数言語のビルトインサポート
- ワンクリックDeepL翻訳統合
- 編集中のロケール切り替え
- 柔軟なi18n構造(ファイル、フォルダ、単一ファイル)
-
ビルトイン画像最適化
- WebP自動変換
- クライアントサイドのリサイズと最適化
- SVG最適化サポート
- 品質とサイズの設定可能
現在のバージョン
- @sveltia/cms: 0.113.5(2025年10月)
- ステータス: 公開ベータ(v1.0は2026年初頭予定)
- 成熟度: プロダクション対応(先行システムからの265以上の課題を解決)
このスキルを使うタイミング
✅ Sveltia CMSを使用すべき場合
-
静的サイトの構築
- Hugoブログとドキュメント
- JekyllサイトとGitHub Pages
- 11ty(Eleventy)プロジェクト
- Gatsbyマーケティングサイト
- Astroコンテンツ重視サイト
-
非技術系編集者がアクセスする必要がある場合
- ページ管理を行うマーケティングチーム
- ブログ記事を執筆する著者
- Git知識のないコンテンツチーム
- 簡単なコンテンツ更新が必要なクライアント
-
Gitベースのワークフローが必要な場合
- Gitによるコンテンツのバージョン管理
- プルリクエストによるコンテンツレビュー
- コンテンツがリポジトリ内でコードと共存
- デプロイのためのCI/CD統合
-
軽量なソリューションが必要な場合
- パフォーマンスが重要なプロジェクト
- モバイルファーストの編集が必要な場合
- 素早い読み込み時間が重要な場合
- 最小限のバンドルサイズが重要な場合
-
Decap/Netlify CMSからの移行
- 既存のconfig.ymlを再利用可能
- ドロップイン置換(1行の変更)
- パフォーマンスとUXの向上
- アクティブなメンテナンスとバグ修正
❌ Sveltia CMSを使用すべきでない場合
-
リアルタイムコラボレーションが必要な場合
- 複数ユーザーが同時に編集(Google Docs形式)
- Sanity、Contentful、TinaCMSを使用
-
ビジュアルページビルダーが必要な場合
- ドラッグ&ドロップのページビルダーが必要
- Webflow、Builder.io、TinaCMS(React)を使用
-
高度に動的なデータが必要な場合
- リアルタイム在庫管理を伴うEコマース
- リアルタイムダッシュボードや分析
- 従来のデータベース(D1、PostgreSQL)を使用
-
React固有のビジュアル編集が必要な場合
- コンテキスト内コンポーネント編集
- 代わりにTinaCMSを使用(React特化)
Sveltia CMS vs TinaCMS
Sveltiaを使用する場合:
- Hugo、Jekyll、11ty、Gatsby(非React SSG)
- 従来のCMS管理パネルUX
- 軽量バンドル要件
- フレームワーク非依存プロジェクト
TinaCMSを使用する場合:
- React、Next.js、Astro(Reactコンポーネント)
- ビジュアルなコンテキスト内編集
- スキーマ駆動の型安全コンテンツ
- TypeScriptによるモダンな開発者体験
どちらも有効 - SveltiaはTinaCMSとは異なるユースケースを補完します。
フレームワーク別セットアップパターン
フレームワークに応じて適切なセットアップパターンを使用してください。
1. Hugoセットアップ(最も一般的)
HugoはSveltia CMSで最も人気のある静的サイトジェネレーターです。
手順:
-
adminディレクトリを作成:
mkdir -p static/admin -
adminインデックスページを作成:
<!-- static/admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
設定ファイルを作成:
# static/admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: static/images/uploads public_folder: /images/uploads collections: - name: posts label: Blog Posts folder: content/posts create: true slug: '{{year}}-{{month}}-{{day}}-{{slug}}' fields: - { label: 'Title', name: 'title', widget: 'string' } - { label: 'Date', name: 'date', widget: 'datetime' } - { label: 'Draft', name: 'draft', widget: 'boolean', default: true } - { label: 'Tags', name: 'tags', widget: 'list', required: false } - { label: 'Body', name: 'body', widget: 'markdown' } -
Hugo開発サーバーを起動:
hugo server -
管理画面にアクセス:
http://localhost:1313/admin/
テンプレート: templates/hugo/ を参照
2. Jekyllセットアップ
JekyllはGitHub PagesおよびSveltia CMSでよく使用されます。
手順:
-
adminディレクトリを作成:
mkdir -p admin -
adminインデックスページを作成:
<!-- admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
設定ファイルを作成:
# admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: assets/images/uploads public_folder: /assets/images/uploads collections: - name: posts label: Blog Posts folder: _posts create: true slug: '{{year}}-{{month}}-{{day}}-{{slug}}' fields: - { label: 'Layout', name: 'layout', widget: 'hidden', default: 'post' } - { label: 'Title', name: 'title', widget: 'string' } - { label: 'Date', name: 'date', widget: 'datetime' } - { label: 'Categories', name: 'categories', widget: 'list', required: false } - { label: 'Body', name: 'body', widget: 'markdown' } -
Jekyll開発サーバーを起動:
bundle exec jekyll serve -
管理画面にアクセス:
http://localhost:4000/admin/
テンプレート: templates/jekyll/ を参照
3. 11ty(Eleventy)セットアップ
11tyは柔軟な静的サイトでSveltia CMSとよく連携します。
手順:
-
adminディレクトリを作成:
mkdir -p admin -
adminインデックスページを作成:
<!-- admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
設定ファイルを作成:
# admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: src/assets/images public_folder: /assets/images collections: - name: blog label: Blog Posts folder: src/posts create: true slug: '{{slug}}' fields: - { label: 'Title', name: 'title', widget: 'string' } - { label: 'Description', name: 'description', widget: 'text' } - { label: 'Date', name: 'date', widget: 'datetime' } - { label: 'Tags', name: 'tags', widget: 'list', required: false } - { label: 'Body', name: 'body', widget: 'markdown' } -
.eleventy.jsにパススルーコピーを追加:module.exports = function(eleventyConfig) { eleventyConfig.addPassthroughCopy('admin'); // ... その他の設定 }; -
11ty開発サーバーを起動:
npx @11ty/eleventy --serve -
管理画面にアクセス:
http://localhost:8080/admin/
テンプレート: templates/11ty/ を参照
4. Astroセットアップ
AstroはSveltia CMSとよく連携するモダンなフレームワークです。
手順:
-
adminディレクトリを作成:
mkdir -p public/admin -
adminインデックスページを作成:
<!-- public/admin/index.html --> <!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
設定ファイルを作成:
# public/admin/config.yml backend: name: github repo: owner/repo branch: main media_folder: public/images public_folder: /images collections: - name: blog label: Blog Posts folder: src/content/blog create: true slug: '{{slug}}' format: mdx fields: - { label: 'Title', name: 'title', widget: 'string' } - { label: 'Description', name: 'description', widget: 'text' } - { label: 'Published Date', name: 'pubDate', widget: 'datetime' } - { label: 'Hero Image', name: 'heroImage', widget: 'image', required: false } - { label: 'Body', name: 'body', widget: 'markdown' } -
Astro開発サーバーを起動:
npm run dev -
管理画面にアクセス:
http://localhost:4321/admin/
テンプレート: templates/astro/ を参照
5. フレームワーク非依存セットアップ
対象: Gatsby、Next.js(SSGモード)、SvelteKit、Remix、または任意のフレームワーク
手順:
-
publicディレクトリを確認:
- Gatsby:
static/ - Next.js:
public/ - SvelteKit:
static/ - Remix:
public/
- Gatsby:
-
publicフォルダ内にadminディレクトリを作成:
mkdir -p <public-folder>/admin -
adminインデックスページを作成:
<!doctype html> <html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> </body> </html> -
コンテンツ構造に合わせた設定ファイルを作成:
backend: name: github repo: owner/repo branch: main media_folder: <your-media-path> public_folder: <your-public-path> collections: # コンテンツ構造に基づいて定義 -
管理画面にアクセス:
http://localhost:<port>/admin/
認証設定
デプロイプラットフォームに適した認証方法を選択してください。
オプション1: Cloudflare Workers OAuth(推奨)🔥
最適: Cloudflare Pages、Cloudflare Workers、任意のデプロイ
公式の sveltia-cms-auth Cloudflare WorkerをOAuthに使用します。
手順:
-
Workerをデプロイ:
# 認証Workerをクローン git clone https://github.com/sveltia/sveltia-cms-auth cd sveltia-cms-auth # 依存関係をインストール npm install # Cloudflare Workersにデプロイ npx wrangler deployまたはワンクリックデプロイ:
- https://github.com/sveltia/sveltia-cms-auth にアクセス
- 「Deploy to Cloudflare Workers」ボタンをクリック
-
GitHubでOAuthアプリを登録:
- https://github.com/settings/developers にアクセス
- 「New OAuth App」をクリック
- アプリケーション名: Your Site Name CMS
- Homepage URL: https://yourdomain.com
- Authorization callback URL: https://your-worker.workers.dev/callback
- Client IDとClient Secretを保存
-
Worker環境変数を設定:
# GitHub認証情報を設定 npx wrangler secret put GITHUB_CLIENT_ID # Client IDを貼り付け npx wrangler secret put GITHUB_CLIENT_SECRET # Client Secretを貼り付け # オプション: 特定のドメインに制限 npx wrangler secret put ALLOWED_DOMAINS # 例: yourdomain.com,*.yourdomain.com -
CMS設定を更新:
# admin/config.yml backend: name: github repo: owner/repo branch: main base_url: https://your-worker.workers.dev # ← この行を追加 -
認証をテスト:
- サイトの
/admin/を開く - 「Login with GitHub」をクリック
- アプリを認可
- CMSにリダイレクトされることを確認
- サイトの
完全ガイド: references/cloudflare-auth-setup.md を参照
テンプレート: templates/cloudflare-workers/ を参照
オプション2: Vercel Serverless Functions
最適: Vercelデプロイ
手順:
-
APIルートを作成:
// api/auth.ts export default async function handler(req, res) { // OAuth処理ロジック // templates/vercel-serverless/api-auth.ts を参照 } -
Vercelで環境変数を設定:
GITHUB_CLIENT_ID=your_client_id GITHUB_CLIENT_SECRET=your_client_secret -
CMS設定を更新:
backend: name: github repo: owner/repo branch: main base_url: https://yourdomain.com/api/auth -
デプロイしてテスト
テンプレート: templates/vercel-serverless/ を参照
オプション3: Netlify Functions
最適: Netlifyデプロイ
手順:
-
関数ディレクトリを作成:
mkdir -p netlify/functions -
認証関数を作成:
// netlify/functions/auth.js // 完全な実装は templates/netlify-functions/auth.js を参照 -
関数に依存関係をインストール:
cd netlify/functions npm init -y npm install node-fetch -
GitHub OAuthアプリのコールバックURLを設定:
https://yourdomain.com/.netlify/functions/auth -
Netlifyで環境変数を設定:
GITHUB_CLIENT_ID=your_client_id GITHUB_CLIENT_SECRET=your_client_secret -
CMS設定を更新:
backend: name: github repo: owner/repo branch: main base_url: https://yourdomain.com/.netlify/functions/auth
テンプレート: templates/netlify-functions/ を参照
トラブルシューティング
Sveltia CMSの一般的な問題とその解決策。
認証問題
-
「Not Allowed」エラー
- 原因: OAuthアプリのコールバックURLが不正
- 解決策: GitHub OAuth設定のコールバックURLを確認
- ワイルドカードは許可されていない
- 正確なURLを使用:
https://your-worker.workers.dev/callback
-
「Failed to get token」エラー
- 原因: 環境変数
GITHUB_CLIENT_SECRETが未設定または不正 - 解決策: Workerまたはサーバーレス関数でシークレットが正しく設定されていることを確認
npx wrangler secret list
- 原因: 環境変数
-
HTTPSリダイレクトループ
- 原因: CloudflareのSSL/TLS設定(Flexible vs Full)
- 解決策: CloudflareダッシュボードでSSL/TLS暗号化モードを「Full」に設定
-
認証後の404エラー
- 原因: コールバックURLの不一致
- 解決策: Workerのルートパス
/callbackが正しく定義されていることを確認
-
「Unknown auth error」エラー
- 原因: 一般的な認証設定の問題
- 解決策: Workerまたはサーバーレス関数のログを確認
npx wrangler tail
CORS/COOP問題
これらの問題は通常、管理画面が読み込まれない、または空白の画面になることで現れます。
-
「Cross-Origin-Embedder-Policy」エラー
- 解決策1: HTTPヘッダーを設定
# Cloudflare Pagesの場合 # _headersファイルを作成 /admin/* Cross-Origin-Embedder-Policy: unsafe-none Cross-Origin-Opener-Policy: same-origin-allow-popups - 解決策2: 安全でないレスポンスを許可するためJavaScriptをモジュールとして読み込む(上記の
type="module"スクリプトタグがこれを処理) - 解決策3: Cloudflare Pagesのカスタムヘッダーを使用
# ダッシュボード > Webサイト > Pages > your-site > Settings > Headers Path: /admin/* Header name: Cross-Origin-Embedder-Policy Value: unsafe-none
- 解決策1: HTTPヘッダーを設定
-
CORSエラー(画像アップロード)
- 症状: 画像をアップロードできない
- 解決策: サイトのルートに
_headersファイルを追加してCORSを有効にする# _headers /admin/* Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, PUT Access-Control-Allow-Headers: Content-Type
-
「Content Security Policy」エラー
- 症状: スクリプトが読み込まれない
- 解決策: CSPヘッダーに
https://unpkg.comを追加Content-Security-Policy: default-src 'self' https://unpkg.com; script-src 'self' https://unpkg.com
設定の問題
-
コレクションが表示されない
- 原因:
config.ymlのインデントエラー - 解決策: YAMLファイルをYAML lintで検証
yamllint admin/config.yml - 一般的な問題:
- タブの代わりにスペースを使用
- 一貫したインデント(2スペース)
- 文字列の引用符が正しいこと
- 原因:
-
YAMLパースエラー
- 原因: 特殊文字が正しくエスケープされていない
- 一般的な問題:
- 引用符で囲まれていない文字列内のコロン
- 引用符で囲まれていない文字列内のハッシュタグ
- 不正なマルチライン文字列
- 解決策: テンプレートリテラルのように値を引用符で囲む
-
メディアファイルがアップロードされない
- 原因:
media_folderパスが不正 - 解決策:
media_folderとpublic_folderがプロジェクト構造と一致していることを確認- GitHub APIはファイルをコミットに依存している
- アップロードするには認証が必要
- 原因:
-
プレビューが機能しない
- 原因: テンプレート変数が利用できない、またはプレビューが正しく設定されていない
- 解決策: Sveltia CMSでプレビュー設定を確認
- 動的プレビューの場合はローカル開発サーバーが必要
- プロダクションビルドが必要な場合もある
デプロイの問題
-
Netlify Functionsのタイムアウト
- 原因: 関数の実行に時間がかかりすぎている
- 解決策: Netlify Functionsのタイムアウト設定を増やす(最大26秒)、またはCloudflare Workersに切り替える(30秒のタイムアウト)
-
静的管理画面が404を返す
- 原因:
admin/ディレクトリが正しくデプロイされていない - 解決策: ビルド出力に
admin/index.htmlが含まれていることを確認- Hugoの場合:
static/admin/index.html - 一般的な場合:
public/admin/index.html
- Hugoの場合:
- 原因:
-
GitHub APIレート制限
- 原因: APIリクエストが多すぎる
- 解決策: コレクション設定を最適化してAPIコールを削減するか、認証付きリクエストのレート制限が高いため認証が正しく機能していることを確認
開発者ツールのチェック
これらの問題を診断するには、ブラウザの開発者ツール(F12)を使用します:
- Consoleタブ: エラーメッセージを確認
- Networkタブ: 失敗したリクエストを確認(特に認証関連)
- Applicationタブ: ローカルストレージとCookieを確認
複数のブラウザでテストすることも、問題がブラウザ固有かどうかを特定するのに役立ちます。
移行ガイド
Decap CMS / Netlify CMSからの移行
Sveltia CMSは、設定とコンテンツ構造を維持しながら、大幅なパフォーマンス向上とバグ修正を提供します。
最小限の変更手順:
-
Sveltia CMSを使用するようにadmin/index.htmlを更新:
<!-- Decap CMS(削除) --> <!-- <script src="https://unpkg.com/decap-cms@^3/dist/decap-cms.js"></script> --> <!-- Sveltia CMS(追加) --> <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script> -
設定はそのまま(ほとんどの場合)
- 既存の
config.ymlはSveltia CMSと互換性があります - 一部の非推奨設定は移行が必要な場合があります
- YAMLスキーマは完全に互換性があります
- 既存の
-
**編集者のために新機能を活用:
- ダークモードインターフェース
- 高速コンテンツ読み込み
- 改善されたモバイルUX
自動移行スクリプト:
より大規模な移行については、提供される自動化スクリプトを使用してください:
# 移行スクリプトを実行
./scripts/migrate.sh # または migrate.ps1 (Windows)
スクリプトは:
- 既存の設定をスキャン
- 互換性の問題をチェック
- 古い設定を新しいフォーマットに更新 "> プロヒント: Sveltia CMSはDecap CMSの完全なドロップイン置換えです。多くの場合、HTMLファイル内のスクリプト行を変更するだけで済みます!"
最適化のヒント
パフォーマンスチューニング
-
画像最適化:
- 画像をアップロードするときは自動圧縮を有効にする
- 品質を80%に設定(画質とファイルサイズのバランス)
- レスポンシブ画像にWebP形式を使用
-
コンテンツ整理:
- コレクションをネストしてGit APIコールを削減
- インデックスコレクションを有効にしてコンテンツ一覧を高速化
search: falseですばやく検索する必要のないコレクションを除外
-
キャッシュ:
- CloudflareやNetlifyでブラウザキャッシュを有効にする
- 静的アセット(admin/index.html)のキャッシュ期間を長く設定
- 設定ファイル
config.ymlにバージョンキャッシュバスターを使用
一般的なヒント
-
初期設定をシンプルに:
- 管理画面で複雑なカスタムウィジェットを避ける
- シンプルなstring、text、markdown、datetime、image、booleanウィジェットから始める
- 後で必要に応じてrelation、select、listウィジェットを追加
-
スマートな編集者向け設定:
- 編集者が簡単に識別できるようにコレクションにわかりやすいラベルを付ける
- 編集者をガイドするためにフィールドに説明的な
hint:を追加 - ウィジェットのデフォルト値を使用して入力を簡素化
-
頻繁にテストする:
- 変更をプッシュする前に、ローカルで設定をテストする
- 問題を早期に発見するためにYAML lintを使用
- デプロイする前にダークモードとモバイルビューを確認
テンプレート構造
templates/
├── hugo/
│ └── ...
├── jekyll/
│ └── ...
├── 11ty/
│ └── ...
├── astro/
│ └── ...
├── cloudflare-workers/
│ └── ...
├── vercel-serverless/
│ └── ...
└── netlify-functions/
└── ...
各テンプレートフォルダには、その特定のセットアップに必要なすべてのファイルが含まれています。
参考資料
- 公式ドキュメント: https://github.com/sveltia/sveltia-cms
- 認証Worker: https://github.com/sveltia/sveltia-cms-auth
- 既知の問題とロードマップ: https://github.com/sveltia/sveltia-cms/issues
内部リファレンス
references/cloudflare-auth-setup.md- Cloudflare Workersを使用した完全な認証ガイドreferences/config-reference.md- すべての設定オプションの詳細なリファレンスreferences/troubleshooting-guide.md- 拡張トラブルシューティングガイド