nuxt-studio

Nuxt Studio のセットアップとデプロイ

概要

Nuxt Studio は、Nuxt Content のウェブサイト向けの無料のオープンソース・ビジュアルコンテンツエディターです。本番環境でコンテンツを直接編集できます。複数のエディタータイプ（Monaco コードエディター、TipTap ビジュアル WYSIWYG エディター、フォームベースのエディター）、OAuth 認証（GitHub／GitLab／Google）、コミット連携を備えた Git ベースのコンテンツ管理を提供します。

主な用途：既存の Nuxt Content ウェブサイトにビジュアル CMS 機能を追加します。通常は studio.domain.com や cms.domain.com などのサブドメインにデプロイします。

このスキルを使用する場合

以下の場合にこのスキルを使用します。

• Nuxt Content のウェブサイトで、初めて Nuxt Studio をセットアップする
• Studio へのアクセスに使う OAuth 認証を設定する
• カスタムサブドメインを使用して、Studio を Cloudflare Pages または Workers にデプロイする
• Studio の認証、ビルド、デプロイに関する問題を解決する
• エディタータイプを設定する、または Studio の動作をカスタマイズする
• 既存の Nuxt v3/v4 アプリケーションに Studio を統合する

前提条件の確認

Studio のセットアップを進める前に、以下の要件を確認してください。

1. Nuxt のバージョン：≥3.x（Studio には Nuxt 3 が必要です）
2. @nuxt/content モジュール：≥2.x（必須の依存関係です）
3. Node.js：≥20.x を推奨
4. Cloudflare アカウント：Cloudflare へのデプロイに必要です（他のプラットフォームでは任意です）

Nuxt Content のインストールを確認する：

# Verify @nuxt/content is installed
grep "@nuxt/content" package.json

# Check nuxt.config.ts for content module
grep "modules.*content" nuxt.config.ts

Nuxt Content がインストールされていない場合は、先にインストールしてください。

npx nuxi module add content

インストール

1. Nuxt Studio モジュールをインストールする

最新のベータ版をインストールします（2025年12月時点で v1.0.0-beta.3）。

npx nuxi module add nuxt-studio@beta

これにより、@nuxt/studio が devDependencies に追加され、nuxt.config.ts でモジュールが設定されます。

2. モジュールの設定を確認する

nuxt.config.ts に Studio モジュールが含まれていることを確認します。

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/content',
    '@nuxt/studio'  // Added automatically
  ]
})

3. 開発モードを開始する

開発サーバーを実行して、Studio がローカルで動作することを確認します。

npm run dev
# or
bun dev

開発モードでは、http://localhost:3000/_studio から Studio にアクセスできます。

OAuth 認証のセットアップ

本番環境にデプロイする場合、Studio には OAuth 認証が必要です。プロバイダーを1つ選択してください。

対応プロバイダー

• GitHub OAuth：公開リポジトリや GitHub でホストされているプロジェクトに最適です
• GitLab OAuth：セルフホストされた GitLab インスタンスに最適です
• Google OAuth：あらゆる構成で使える汎用的な選択肢です

OAuth の簡易設定

各プロバイダーの詳細な OAuth セットアップ手順については、references/oauth-providers.md を読み込んでください。

環境変数の形式（すべてのプロバイダー共通）：

# GitHub
NUXT_OAUTH_GITHUB_CLIENT_ID=your_client_id
NUXT_OAUTH_GITHUB_CLIENT_SECRET=your_client_secret

# GitLab
NUXT_OAUTH_GITLAB_CLIENT_ID=your_client_id
NUXT_OAUTH_GITLAB_CLIENT_SECRET=your_client_secret

# Google
NUXT_OAUTH_GOOGLE_CLIENT_ID=your_client_id
NUXT_OAUTH_GOOGLE_CLIENT_SECRET=your_client_secret

コールバック URL の形式：

https://studio.yourdomain.com/api/auth/callback/[provider]

[provider] を github、gitlab、または google に置き換えてください。

OAuth アプリの作成手順については、references/oauth-providers.md を参照してください。

Cloudflare へのデプロイ

Studio は Cloudflare Pages および Workers で快適に動作します。以下の場合は、Cloudflare へのデプロイを使用してください。

• サーバーレスのエッジデプロイ
• カスタムサブドメインのルーティング（例：studio.domain.com）
• ダッシュボードでの環境変数管理
• Git からの自動ビルド

Cloudflare セットアップの概要

1. nuxt.config.ts で Cloudflare 用の Nitro プリセットを設定する
2. Workers へのデプロイ用に wrangler.toml を作成または更新する（任意）
3. Cloudflare ダッシュボードで 環境変数を設定する
4. カスタムドメインとサブドメインのルーティングを設定する
5. Cloudflare Pages または Workers 経由で デプロイする

Cloudflare へのデプロイ手順の詳細については、references/cloudflare-deployment.md を読み込んでください。

Cloudflare の簡易設定

Cloudflare Pages プリセットを設定します。

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/content', '@nuxt/studio'],

  nitro: {
    preset: 'cloudflare-pages'
  }
})

カスタムサブドメインのルーティングを使用した Workers へのデプロイについては、references/cloudflare-deployment.md を参照してください。

エディタータイプ

Studio では、コンテンツタイプごとに設定できる3種類のエディターを利用できます。

1. Monaco Editor：Markdown、YAML、JSON 用のコードエディター
2. TipTap Editor：MDC コンポーネントをサポートするビジュアル WYSIWYG エディター（デフォルト）
3. Form Editor：YAML／JSON ファイル用のスキーマ駆動型フォーム

デフォルトのエディターを設定する

// nuxt.config.ts
export default defineNuxtConfig({
  studio: {
    editor: {
      default: 'tiptap'  // or 'monaco' or 'form'
    }
  }
})

エディターの設定オプションについて詳しくは、references/editor-configuration.md を読み込んでください。

サブドメインの設定

本番環境で使用するため、Studio をサブドメインにデプロイします。

一般的なパターン：

• studio.yourdomain.com
• cms.yourdomain.com
• edit.yourdomain.com
• admin.yourdomain.com

DNS の設定

1. DNS プロバイダーで CNAME レコードを追加します
2. サブドメインを Cloudflare Pages のデプロイ先に指定します
3. Cloudflare Pages の設定でカスタムドメインを構成します

Cloudflare を使用したサブドメインの完全な設定手順については、references/subdomain-setup.md を読み込んでください。

よくあるエラー上位 5 件

1. OAuth リダイレクト URI の不一致

エラー：認証ループ、または「redirect_uri_mismatch」エラーが発生します

原因：OAuth アプリのコールバック URL が実際のデプロイ URL と一致していません

解決方法：

Ensure OAuth app callback URL is:
https://studio.yourdomain.com/api/auth/callback/[provider]

Not:
https://yourdomain.com/api/auth/callback/[provider]

2. モジュールが見つかりません：@nuxt/studio

エラー：Cannot find module '@nuxt/studio'

原因：Studio モジュールがインストールされていないか、正しくインストールされていません

解決方法：

npx nuxi module add nuxt-studio@beta
# or
npm install -D @nuxt/studio

3. Cloudflare Pages のビルド失敗

エラー：「Incompatible module」またはランタイムエラーが発生し、ビルドが失敗します

原因：Nitro プリセットが Cloudflare 用に設定されていません

解決方法：

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare-pages'
  }
})

4. ログイン後に認証ループが発生する

エラー：OAuth に成功した後、ログイン画面に繰り返しリダイレクトされます

原因：ドメインの不一致により、セッション Cookie が保持されていません

解決方法：

• NUXT_PUBLIC_STUDIO_URL 環境変数がデプロイ URL と一致することを確認します
• ブラウザーの Cookie 設定を確認します（OAuth ではサードパーティ Cookie を許可する必要があります）
• デプロイ URL が HTTPS を使用していることを確認します（HTTP ではなく HTTPS）

5. サブドメインのルーティングが機能しない

エラー：サブドメインではなく、メインドメインで Studio が読み込まれます

原因：DNS または wrangler の設定が正しくありません

解決方法：

• CNAME レコードが Cloudflare Pages を指していることを確認します
• Cloudflare ダッシュボードでカスタムドメインの設定を確認します
• Workers の場合：wrangler.toml のルート設定を確認します

エラーと解決方法の完全な一覧については、references/troubleshooting.md を読み込んでください。

テンプレートの使用

このスキルには、動作する設定テンプレートが含まれています。

• templates/nuxt.config.ts：Studio モジュールの完全な設定
• templates/wrangler.toml：Cloudflare Workers のデプロイ設定
• templates/studio-auth-github.ts：GitHub OAuth の実装
• templates/studio-auth-gitlab.ts：GitLab OAuth の実装
• templates/studio-auth-google.ts：Google OAuth の実装

これらを Studio の設定の出発点として使用してください。

開発ワークフロー

ローカル開発

1. Studio モジュールをインストールします：npx nuxi module add nuxt-studio@beta
2. 開発サーバーを起動します：npm run dev
3. Studio にアクセスします：http://localhost:3000/_studio
4. コンテンツをビジュアルに編集します
5. Studio UI から変更をコミットします

本番環境へのデプロイ

1. OAuth プロバイダーを設定します（GitHub/GitLab/Google）
2. デプロイプラットフォームで環境変数を設定します
3. 対象プラットフォーム用に Nitro プリセットを設定します
4. Cloudflare Pages/Workers またはその他のプラットフォームにデプロイします
5. カスタムサブドメインを設定します
6. 認証とコンテンツ編集をテストします

検証チェックリスト

Studio を本番環境にデプロイする前に、次の項目を確認してください。

• Nuxt Content がインストールされ、設定されている（≥v2.x）
• Nuxt のバージョンが ≥3.x
• @nuxt/studio モジュールがインストールされている
• 有効な認証情報を使用して OAuth プロバイダーが設定されている
• 環境変数が正しく設定されている
• デプロイプラットフォーム用に Nitro プリセットが設定されている
• カスタムサブドメインの DNS が設定されている
• コールバック URL がデプロイ URL と一致している
• サブドメインの URL で Studio にアクセスできる
• 認証が正しく機能している
• コンテンツの編集とコミット機能がテストされている

リファレンスの読み込みタイミング

特定の作業を行う際は、次のリファレンスファイルを読み込んでください。

• OAuth のセットアップ：GitHub／GitLab／Google の OAuth アプリの作成方法について詳しくは、references/oauth-providers.md を読み込んでください
• Cloudflare へのデプロイ：wrangler、カスタムドメイン、環境変数を含む Cloudflare Pages／Workers のセットアップ手順について詳しくは、references/cloudflare-deployment.md を読み込んでください
• エディターの設定：Monaco／TipTap／Form エディターのカスタマイズについて詳しくは、references/editor-configuration.md を読み込んでください
• サブドメインの設定：DNS とルーティングの設定について詳しくは、references/subdomain-setup.md を読み込んでください
• トラブルシューティング：包括的なエラー解決方法とデバッグについては、references/troubleshooting.md を読み込んでください

ユーティリティスクリプト

一般的な操作には、次の付属スクリプトを使用してください。

• scripts/check-prerequisites.sh：Nuxt Content とバージョン要件を確認します
• scripts/validate-config.sh：nuxt.config.ts の Studio 設定を確認します
• scripts/test-oauth.sh：OAuth 環境変数の設定をテストします

次のコマンドでスクリプトを実行します。

bash $CLAUDE_PLUGIN_ROOT/skills/nuxt-studio/scripts/script-name.sh

他のスキルとの連携

このスキルは、次のスキルと相性が良好です。

• nuxt-content：Studio の前提条件（content モジュールが必要）
• nuxt-v4：設定に必要な Nuxt フレームワークの基礎知識
• cloudflare-worker-base：Cloudflare へのデプロイの基礎
• better-auth：カスタム認証が必要な場合の代替認証パターン

追加リソース

• Nuxt Studio リポジトリ：https://github.com/nuxt-content/studio
• Nuxt Content ドキュメント：https://content.nuxt.com
• Cloudflare Pages：https://pages.cloudflare.com
• OAuth ドキュメント：GitHub／GitLab／Google の開発者向けドキュメント

バージョン情報

• Nuxt Studio：v1.0.0-beta.3（2025年12月時点の最新バージョン）
• Nuxt：≥3.x が必要です
• @nuxt/content：≥2.x が必要です
• Node.js：≥20.x を推奨します

最新のバージョン情報は、こちらを確認してください：https://github.com/nuxt-content/studio/releases

---

次のステップ：Studio の設定後、デプロイを十分にテストし、OAuth 認証が正しく機能すること、コンテンツの編集と Git コミットが期待どおりに動作することを確認してください。