sveltia-cms

Sveltia CMS スキル

静的サイトプロジェクトに Sveltia CMS を統合するための包括的なスキルです。

---

Sveltia CMS とは？

Sveltia CMS は、Decap CMS（旧 Netlify CMS）の現代的な後継としてゼロから構築された、Git ベースの軽量なヘッドレスコンテンツ管理システムです。Git リポジトリに保存されたコンテンツを、すばやく直感的に編集できるインターフェースを提供します。

主な機能

1. 軽量で高速

   • バンドルサイズ：<500 KB（圧縮・brotlied）で、競合製品の 1.5-2.6 MB より小さい
   • Svelte コンパイラーを使用して構築（仮想 DOM によるオーバーヘッドなし）
   • GraphQL API を使用してコンテンツを即座に取得
   • すべてのコンテンツを対象に関連度ベースで検索

2. モダンなユーザー体験

   • ビューポート全体を活用する直感的な管理インターフェース
   • ダークモード対応（システム設定に従います）
   • モバイルとタブレットに最適化
   • 複数ファイルに対応したドラッグ＆ドロップでのファイルアップロード
   • 即時更新されるリアルタイムプレビュー

3. Git ネイティブなアーキテクチャ

   • コンテンツを Markdown、MDX、YAML、TOML、または JSON として保存
   • 完全なバージョン管理と変更履歴
   • ベンダーロックインなし — コンテンツはコードとともに保存
   • GitHub、GitLab、Gitea、Forgejo のバックエンドに対応

4. フレームワークに依存しない

   • バニラ JavaScript バンドルとして配信
   • Hugo、Jekyll、11ty、Gatsby、Astro、Next.js、SvelteKit で動作
   • React、Vue、フレームワークのランタイム依存なし
   • あらゆる静的サイトジェネレーターと互換性あり

5. 多言語化を標準搭載

   • 複数言語への対応を標準搭載
   • ワンクリックで DeepL 翻訳を連携
   • 編集中にロケールを切り替え
   • 柔軟な i18n 構造（ファイル、フォルダー、単一ファイル）

6. 画像最適化機能を標準搭載

   • WebP への自動変換
   • クライアント側でのサイズ変更と最適化
   • SVG 最適化に対応
   • 品質とサイズを設定可能

現在のバージョン

• @sveltia/cms: 0.113.5（2025年10月）
• ステータス: パブリックベータ（v1.0 は 2026年初頭にリリース予定）
• 成熟度: 本番環境で利用可能（前身から 265 件以上の問題を解決）

---

このスキルを使う場合

✅ Sveltia CMS を使う場面：

1. 静的サイトを構築する

   • Hugo のブログやドキュメント
   • Jekyll サイトや GitHub Pages
   • 11ty（Eleventy）プロジェクト
   • Gatsby のマーケティングサイト
   • コンテンツの多い Astro サイト

2. 技術に詳しくない編集者がアクセスする必要がある

   • ページを管理するマーケティングチーム
   • ブログ記事を執筆する著者
   • Git の知識がないコンテンツチーム
   • コンテンツを簡単に更新したいクライアント

3. Git ベースのワークフローが望ましい

   • Git によるコンテンツのバージョン管理
   • プルリクエストによるコンテンツレビュー
   • リポジトリ内でコンテンツをコードとともに管理
   • デプロイのための CI/CD 連携

4. 軽量なソリューションが必要

   • パフォーマンスが重視されるプロジェクト
   • モバイルファーストの編集が必要
   • 高速な読み込みが重要
   • 最小限のバンドルサイズが重要

5. Decap/Netlify CMS から移行する

   • 既存の config.yml を再利用可能
   • そのまま置き換え可能（1 行を変更）
   • パフォーマンスと UX が向上
   • 積極的なメンテナンスとバグ修正

❌ Sveltia CMS を使わない場面：

1. リアルタイムの共同編集が必要

   • 複数ユーザーが同時に編集する（Google Docs のような形式）
   • 代わりに Sanity、Contentful、または TinaCMS を使用

2. ビジュアルなページ作成が必要

   • ドラッグ＆ドロップ式のページビルダーが必要
   • 代わりに Webflow、Builder.io、または TinaCMS（React）を使用

3. 高度に動的なデータを扱う

   • リアルタイムの在庫管理を伴う E コマース
   • リアルタイムのダッシュボードや分析
   • 代わりに従来型のデータベース（D1、PostgreSQL）を使用

4. React 固有のビジュアル編集が必要

   • コンテキスト内でのコンポーネント編集
   • 代わりに TinaCMS を使用（React に特化）

Sveltia CMS と TinaCMS の比較

次の用途には Sveltia を使用します：

• Hugo、Jekyll、11ty、Gatsby（React を使用しない SSG）
• 従来型 CMS の管理パネルの UX
• 軽量なバンドルが求められる場合
• フレームワークに依存しないプロジェクト

次の用途には TinaCMS を使用します：

• React、Next.js、Astro（React コンポーネント）
• コンテキスト内でのビジュアル編集
• スキーマ駆動の型安全なコンテンツ
• TypeScript を使用したモダンな開発者体験

どちらも有効な選択肢です。用途に応じて Sveltia は TinaCMS を補完します。

---

クイックスタート

フレームワークごとの完全なセットアップ手順については、references/framework-setup.md を読み込んでください（Hugo、Jekyll、11ty、Astro、Next.js、Gatsby、SvelteKit）。

基本的なセットアップ手順（フレームワーク共通）

1. 公開フォルダーに管理ディレクトリを作成します（例：static/admin、public/admin）。
2. Sveltia CMS のスクリプトタグを含む admin/index.html を作成します。
3. バックエンドとコレクションを含む admin/config.yml を作成します。
4. 認証をセットアップします → references/authentication-guide.md を参照してください。
5. /admin/ にアクセスしてローカルでテストします。

各フレームワーク用のテンプレートが templates/ ディレクトリにあります。

---

認証のセットアップ

OAuth の完全なセットアップ手順については、references/authentication-guide.md を読み込んでください。

概要

方法	最適な用途	複雑さ
Cloudflare Workers	すべてのデプロイ	簡単 ⭐
Vercel Serverless	Vercel プロジェクト	中程度
ローカル開発	開発のみ	簡単

推奨：Cloudflare Workers OAuth（公式、高速、無料）

テンプレート：templates/cloudflare-workers/ と templates/vercel-serverless/ を参照してください。

---

設定

config.yml の完全なドキュメント、コレクションのパターン、i18n のセットアップについては、references/configuration-guide.md を読み込んでください。

基本的な設定構造

backend:
  name: github
  repo: owner/repo
  branch: main
  base_url: https://your-worker.workers.dev

media_folder: static/images
public_folder: /images

collections:
  - name: posts
    label: Blog Posts
    folder: content/posts
    create: true
    fields:
      - { label: Title, name: title, widget: string }
      - { label: Body, name: body, widget: markdown }

ブログ、ドキュメント、ランディングページ用のコレクションテンプレートが templates/collections/ にあります。

i18n サポート：複数ファイル、フォルダー、単一ファイルの各構成については、リファレンスガイドを参照してください。

---

よくあるエラーと解決策

このスキルでは、よくある 8 つのエラーを防止します。以下に上位 3 つを示します。8 つすべての完全な解決策については、references/error-catalog.md を読み込んでください。

1. ❌ OAuth 認証の失敗

エラー：「Error: Failed to authenticate」／誤ったドメインにリダイレクトされる

簡単な修正方法：

• config.yml の base_url が OAuth プロキシを指していることを確認します。
• GitHub OAuth のコールバック URL が Worker の URL と一致することを確認します。
• Worker をテストします：curl https://your-worker.workers.dev/health

→ 完全な解決策については、references/error-catalog.md のエラー #1 を読み込んでください

---

2. ❌ CMS にコンテンツが一覧表示されない

エラー：「No entries found」／コンテンツ一覧が空

簡単な修正方法：

• folder のパスが実際のファイルの場所と一致することを確認します。
• format を実際のファイル形式（yaml または toml）に合わせます。
• ファイル拡張子が設定と一致することを確認します。

→ 完全な解決策については、references/error-catalog.md のエラー #4 を読み込んでください

---

3. ❌ CORS／COOP ポリシーエラー

エラー：「Authentication Aborted」／OAuth ポップアップが閉じる

簡単な修正方法：

• ヘッダーに Cross-Origin-Opener-Policy: same-origin-allow-popups を設定します。
• CSP の connect-src に OAuth プロキシを追加します。

→ 完全な解決策については、references/error-catalog.md のエラー #8 を読み込んでください

---

詳細な解決策を含む 8 つのエラーすべてについては、references/error-catalog.md を参照してください

---

Decap CMS からの移行

Sveltia はそのまま置き換えられます。スクリプトタグを変更するだけです。

<script src="https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js"></script>


<script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js" type="module"></script>

既存の config.yml はそのまま動作します。移行ガイドとテストチェックリストの完全版については、references/migration-from-decap.md を読み込んでください。

---

デプロイ

プラットフォームごとのデプロイ手順については、references/deployment-guide.md を読み込んでください（Cloudflare Pages、Vercel、Netlify、GitHub Pages）。

デプロイのクイックチェックリスト

• 管理ディレクトリが正しい公開フォルダーにある
• OAuth プロキシがデプロイされ、設定されている
• config.yml に base_url が設定されている
• ビルドコマンドが設定されている
• デプロイ後に /admin/ ルートをテストする

---

参照資料を読み込むタイミング

以下の場合は references/framework-setup.md を読み込んでください：

• Hugo、Jekyll、11ty、Astro など、フレームワーク固有のセットアップが必要な場合
• Sveltia CMS の新しいインストールをセットアップする場合
• フレームワーク固有の管理ディレクトリの問題をトラブルシューティングする場合

以下の場合は references/authentication-guide.md を読み込んでください：

• GitHub OAuth 認証をセットアップする場合
• Cloudflare Workers OAuth プロキシをデプロイする場合
• 認証エラーをトラブルシューティングする場合
• ユーザーが base_url の設定について尋ねた場合

以下の場合は references/configuration-guide.md を読み込んでください：

• config.yml の完全な例が必要な場合
• コレクション、フィールド、ウィジェットをセットアップする場合
• メディアのアップロード、i18n、ワークフローを設定する場合
• ユーザーが特定の設定オプションについて尋ねた場合

以下の場合は references/error-catalog.md を読み込んでください：

• セットアップ中にエラーが発生した場合
• 認証、解析、デプロイに関する問題をトラブルシューティングする場合
• 上記の上位3件以外のエラーがユーザーから報告された場合

以下の場合は references/deployment-guide.md を読み込んでください：

• Cloudflare Pages、Netlify、Vercel にデプロイする場合
• OAuth プロキシのデプロイをセットアップする場合
• 本番環境へのデプロイの問題をトラブルシューティングする場合

以下の場合は references/migration-from-decap.md を読み込んでください：

• Decap CMS／Netlify CMS から移行する場合
• ユーザーが互換性や移行手順について尋ねた場合

---

リソース

テンプレート：templates/hugo/、templates/jekyll/、templates/cloudflare-workers/ 公式ドキュメント：https://github.com/sveltia/sveltia-cms OAuth Worker：https://github.com/sveltia/sveltia-cms-auth

---

パッケージ情報

現行バージョン：@sveltia/[email protected]（2025年10月） ステータス：本番環境で利用可能。v1.0 は2026年初頭にリリース予定

---

最終更新日：2025-10-24