setup-weaverse-project

Weaverse プロジェクトのセットアップ — エージェントスキル

ユーザーが何もない状態から、実行中で接続済みの Weaverse Hydrogen ストアフロントを利用できるようにします。 ここが最初の入口です。他の Weaverse スキルはすべて、プロジェクトがすでに存在することを前提としています。このスキルではプロジェクトを作成します。

オンボーディングを成功させる唯一のルール

認証情報を尋ねる前に、デモストアでライブプレビューを起動してください。

ユーザーの多くは、何かが動く様子を見る前に壁（GitHub、Shopify トークン、CLI）にぶつかり、オンボーディングを途中でやめてしまいます。Weaverse のテーマには .env.example に動作するデモストアのトークンが含まれているため、認証情報なしで約 2 分あれば、実際に動作するストアフロントを表示できます。まずそれを行ってください。「すごい」と思ってもらい、その後でユーザー自身のものにしましょう。

ユーザーがストアフロントの実行を確認する前に、GitHub リポジトリの作成、Shopify ストアの連携、トークンの貼り付けを求めてはいけません。そうした場合、すべてのコマンドが成功してもオンボーディングは失敗です。

CLI はあなたが操作し、ユーザーはブラウザーのフローでクリックするだけです

ユーザー（マーチャントまたは開発者）が CLI コマンドを入力する必要はありません。裏側で shopify hydrogen と @weaverse/cli を実行するのはあなたです。Shopify CLI は実際の処理（環境変数の取得、開発サーバーの起動、コード生成、デプロイ）を行います。再実装せず、CLI を操作してください。npm run dev 自体も shopify hydrogen dev をシェル経由で実行するため、常に CLI が関わります。ユーザーには見えないようにしてください。

人が行う作業は、ブラウザーのフローの承認、ストア選択画面でのストア選択、認証情報のコピー、シークレットの提供に限られます。コマンドの貼り付けを求めてはいけません。

必要な入力

尋ねる内容はできる限り少なくしてください。セットアップに必要な値のほとんどは生成または検出できます。

セットアップのプロンプトまたはユーザーから取得する必須項目：

• WEAVERSE_PROJECT_ID — Weaverse Builder から取得します
• テーマハンドル — 省略された場合のみ pilot をデフォルトにします
• プロジェクトフォルダー名 — my-hydrogen-storefront をデフォルトにします

実際のストアで後から必要になる項目：

• PUBLIC_STORE_DOMAIN
• PUBLIC_STOREFRONT_API_TOKEN

あなたが生成する項目：

• SESSION_SECRET — ユーザーに尋ねず、ランダムな値を生成します

後から指定する任意の項目：

• PRIVATE_STOREFRONT_API_TOKEN
• SHOP_ID
• 顧客アカウント関連の変数
• チェックアウトドメイン
• 分析／レビュー関連の変数

---

フェーズ 0 — 環境を検出する

何かを始める前に、以下を検出して記録します（推測しないでください）。

node --version            # need >= 18
git --version
gh --version 2>/dev/null && gh auth status 2>/dev/null   # is GitHub CLI present AND authed?
npx shopify version 2>/dev/null                          # Shopify CLI availability
npx @weaverse/cli@latest create --help 2>/dev/null        # CLI availability + template choices
ls package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null # infer package manager

以降の手順はこれに基づいて分岐します。gh が存在しない、または認証されていない場合は、フェーズ 6 の手動リポジトリへのフォールバックを使用します。Node のバージョンが 18 未満の場合は停止し、アップグレードするようユーザーに伝えてください。

---

フェーズ 1 — Weaverse CLI でテーマをスキャフォールドする

git clone より Weaverse CLI を優先してください。CLI は対応テンプレートを把握しており、適切なソースをダウンロードし、初期環境変数ファイルを作成します。

npx @weaverse/cli@latest create \
  --template=<theme-handle> \
  --project-id=<WEAVERSE_PROJECT_ID> \
  --project-name=<project-folder> \
  --no-install \
  -y

cd <project-folder>
git init

ルール：

• テーマハンドルが指定されていない場合は、pilot をデフォルトにします。

• CLI がテーマを拒否した場合（古い、または存在しない blank ハンドルなど）、対応テンプレートの一覧を表示し、ユーザーに置き換えるテーマを尋ねます。黙ってテーマを切り替えてはいけません。

• インストールされている CLI が --no-install に対応していない場合は、CLI に依存関係をインストールさせてから、作成されたフォルダーで作業を続けます。

• GitHub のダウンローダーを独自に作成してはいけません。まず CLI を使用し、CLI を利用できずテーマのリポジトリが存在する場合に限り、clone/degit を使用します。

• clone/degit にフォールバックした後、CLI が削除するはずのものを削除し、新しい履歴を開始します。

  rm -rf .git .github .weaverse
  git init
  

  .git はテーマリポジトリの履歴です（その origin はフェーズ 3 の GitHub への push を妨げます）。.github にはテーマ内部のワークフロー（Oxygen のデプロイ、CI、コードレビュー）が含まれていますが、Weaverse のシークレットがないと失敗します。また、.weaverse には内部仕様が含まれています。

---

フェーズ 2 — 感動の瞬間（デモストアで起動）

ここがこの手順の目玉です。Shopify の認証情報を求める前に、デモ用の Shopify 認証情報を使ってライブプレビューを起動します。

まず、サーバーを起動する前に .env が完成していることを確認します（開発サーバーは起動時に環境変数を読み込みます。後から修正する場合は再起動が必要です）。

• CLI で生成した .env には、すでにデモ用の Shopify 値とユーザーの WEAVERSE_PROJECT_ID が含まれているはずです。.env がない場合は、.env.example を .env にコピーしてから、セットアップのプロンプトで設定した WEAVERSE_PROJECT_ID を指定します。
• SESSION_SECRET をユーザーに尋ねてはいけません。値がない場合、またはデモ用のプレースホルダー（例：foobar）のままの場合は、生成して今すぐ .env に書き込みます。

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

次に起動します。

npm install                   # or pnpm/yarn per lockfile
npm run dev                   # boots http://localhost:3456

その後、成功したと伝える前に、実際に起動したことを確認します。

curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456   # expect 200

ユーザーには、わかりやすく次のように伝えます。

「ストアフロントがローカルの http://localhost:3456 で実行されています。これは Weaverse のデモストアです。次に、これをあなたのストアにしましょう。」

プレビューが起動し、確認できるまでは認証情報の設定に進まないでください。

---

フェーズ 3 — ユーザーのストアに切り替える（Shopify の認証情報）

次に、デモストアをユーザーのストアに切り替えます。Weaverse のプレビューを表示するために最低限必要な変数は次のとおりです。

• PUBLIC_STORE_DOMAIN — their-store.myshopify.com
• PUBLIC_STOREFRONT_API_TOKEN — Storefront API アクセストークン
• WEAVERSE_PROJECT_ID — フェーズ 4 を参照（Shopify から取得できない唯一の変数です）

SESSION_SECRET は Hydrogen で引き続き必要ですが、これはエージェントが生成します。それ以外（SHOP_ID、PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID、PUBLIC_CHECKOUT_DOMAIN、PUBLIC_STOREFRONT_ID、分析、レビュー）は機能をすべてそろえるための追加項目です。初回の起動が成功してから設定し、これらの設定を理由に作業を止めないでください。

手順は 1 つ：Hydrogen アプリをインストールしてストアフロントをリンクする

Hydrogen は Shopify の開発ストアで動作します。Headless アプリを使う代替手段はありません。プランにかかわらず、ローカルでのリンクと認証情報の設定にはHydrogen アプリを使用します。

1. ユーザーに Hydrogen アプリをインストールしてもらいます：https://apps.shopify.com/hydrogen。ストアの選択、インストールの承認、アプリ内での Hydrogen ストアフロントプロジェクトの作成が必要な場合があります。
2. ストアフロントをリンクします（あなたが実行します）。

   npx shopify hydrogen link
   

   ストアの選択画面が表示された場合は、選択する正確な .myshopify.com ドメインをユーザーに尋ねてください。ストアの一覧から推測してはいけません。
3. 環境変数を取得します（あなたが実行します）。

   npx shopify hydrogen env pull
   

   これにより、ストアの実際の変数が .env に設定されます。取得処理で上書きされた場合は、WEAVERSE_PROJECT_ID と生成済みの SESSION_SECRET を保持してください。
4. 切り替える前に確認します。未確認の認証情報でデモ用の認証情報を置き換えてはいけません。.env にプレースホルダーではなく実際の値が設定されていることを確認します。

   grep -E "^(PUBLIC_STORE_DOMAIN|PUBLIC_STOREFRONT_API_TOKEN)=" .env
   

   PUBLIC_STORE_DOMAIN がストアの実際の <store>.myshopify.com ドメインであり、PUBLIC_STOREFRONT_API_TOKEN が空でない Storefront API トークンである必要があります。確認できてから切り替えます（取得処理ですでに切り替わっています）。フェーズ 2 の確認をもう一度実行します。

   curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456   # expect 200
   

実際の制限について、ここで一度だけ説明します。 公開 Oxygen 環境や共有可能な本番環境は、引き続きストアの Shopify プランに依存します。一方、ローカルでのリンクと認証情報の設定はプランに依存せず、Hydrogen アプリを通じて開発ストアでも利用できます。 環境のドキュメント：https://shopify.dev/docs/storefronts/headless/hydrogen/environments はじめに：https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started

env pull が利用できない場合、または失敗した場合は、ユーザーに Shopify Admin → Hydrogen アプリ → Storefront settings → Environments and variables から変数をコピーしてもらいます。あなたが表示に必要な最小限の変数を .env に書き込み、上記の手順で確認してください。

フェーズ 4 — プロジェクト ID（WEAVERSE_PROJECT_ID）

WEAVERSE_PROJECT_ID は、Weaverse Builder にのみ存在し、Shopify から導出できない唯一の値です。

Weaverse Builder が生成するセットアッププロンプトには、プロジェクトの WEAVERSE_PROJECT_ID（およびテーマ名）が埋め込まれています。渡されたプロンプトから値を読み取り、.env に書き込んでください。値が渡されていない場合は、ユーザーに Weaverse Studio → Project Settings からコピーするよう依頼してください。

---

フェーズ 5 — Weaverse API トークンと MCP（チャットを利用したライブ編集）

Weaverse MCP を使用すると、エージェントはチャットからこのプロジェクト（および同じショップ上のほかのプロジェクト）を直接読み取り、編集できます。マウントされた Content API を通じたページやコンテンツのライブ書き込みも可能です。

1. トークンを作成します（人間による操作）。 ユーザーが Weaverse Studio → Dashboard → Account/Settings → API Keys（https://studio.weaverse.io）で Weaverse API トークンを作成します。環境変数 WEAVERSE_API_KEY として設定してください。追跡対象のファイルやプロンプトには決して記載しないでください。
2. MCP サーバーを設定します。 エージェントの MCP 設定に @weaverse/mcp@latest を追加し、ベアラー環境変数を次のとおり正確に設定します。

   WEAVERSE_API_KEY=<token>
   

   設定の形式はクライアント（Cursor、Claude Code、Codex、opencode、VS Code、pi など）によって異なります。クライアントごとの正確な設定例はドキュメントを参照してください：https://weaverse.io/docs/developer-tools/weaverse-mcp
3. 読み取りを確認します。 実際の読み取りツールを使用します：list_projects、get_project、list_pages、get_page、get_theme_settings、list_languages、get_openapi_spec。whoami ツールはありません。
4. ライブ書き込みはデフォルトで無効です。同意を得た場合にのみ有効にしてください。 6 つの書き込みツールを使用するには、環境変数を次のとおり正確に設定する必要があります。

   WEAVERSE_ENABLE_LIVE_WRITES=true
   

   有効にすると、次のツールを使用できます：update_project、create_page、delete_pages、update_page、assign_template_resources、update_theme_settings。 有効にする前に、わかりやすい言葉で説明してください。 ライブ書き込みを有効にすると、これらのツールはライブストアフロントのコンテンツを変更します。update_page は実際のページ項目を編集し、create_page／delete_pages は実際のページを作成／削除します。assign_template_resources は、既存の共有テンプレートページ 1 つに Shopify リソースを追加します（別のページから割り当てを変更することはありません。ハンドルがすでに別のライブページに属している場合は、バッチ全体が 409 で拒否され、書き込みは一切行われません）。update_theme_settings はテーマ設定を変更し、update_project はプロジェクト名を変更します。書き込みは Studio で保存した場合と同じキャッシュ無効化経路を通じてすぐに反映されます。別途公開する手順はありません。書き込み後は、変更されたリソースを読み取り直して確認してください。

これは今後の作業を便利にするためのもので、セットアップの完了に必須ではありません。ユーザーが MCP 対応エージェントを使用していない場合は、省略してください。

フェーズ 6 — ユーザーのリポジトリを作成してプッシュする（先に確認）

プッシュすると、ユーザーの GitHub アカウントにリポジトリが作成され、コードが公開されます。これはユーザーの承認が必要な外部への影響です。ローカルのセットアップを妨げないでください。承認が得られなくても、ストアフロントはすでにローカルで動作しており、セットアップの完了を報告できます。

gh repo create、git commit、git pushを実行する前に、必ず確認してください。ghの認証がすでに済んでいる場合も同様です。検出されたghの状態によって決まるのは、承認後の実行方法だけです。それ自体が承認になることはありません。次の内容を確認し、ユーザーに復唱してください。

• 正確なリポジトリ名（デフォルトは<project-folder>）、
• 公開設定（ユーザーから別の指定がない限り、private）、
• 初回プッシュを実行してよいかどうか。

承認後、ghがインストール済みで認証済みの場合（フェーズ 0）：

git add -A
git commit -m "Initial commit: Weaverse Hydrogen storefront"
gh repo create <approved-name> --private --source=. --remote=origin --push

リポジトリ名がすでに存在する場合は、操作する前に内容を確認してください。

gh repo view <owner>/<approved-name> --json isEmpty,sshUrl,url

• 空のリポジトリ → originとして追加してプッシュします。
• 空でないリポジトリ → 上書きや強制プッシュはしないでください。<project-folder>-pilotや<project-folder>-weaverseなどの別名を提案し、その名前で進める前に承認を得てください。

承認後、ghがインストールされていない／認証されていない場合： クリック可能な手順を示し、プッシュを有効にするようユーザーに依頼してください。

1. GitHub CLIを認証する（https://github.com/login）か、https://github.com/newで新しい空のリポジトリを作成します（READMEは追加しません）。
2. 次に、ユーザーのURLを入力して以下を実行します。

   git add -A && git commit -m "Initial commit: Weaverse Hydrogen storefront"
   git remote add origin https://github.com/<user>/<repo>.git
   git branch -M main && git push -u origin main
   

ユーザーが断る、または返答しない場合： その旨を明確に伝え、作業はローカルのみでコミット済み（または未コミット）の状態にして、続行してください。促されない限り、プッシュを再度試みないでください。

.envやシークレットは絶対にコミットしないでください。 .gitignoreが.env*を対象にしていること（スキャフォールドには設定済みです）、トークンがコミットに含まれていないことを確認してください。シークレットがステージングされていた場合は、ステージングを解除してから.gitignoreに追加し、その後コミットしてください。

「エージェントが行う」手順と「ユーザーが行う」手順を、同じ手順として提示しないでください。承認後はフェーズ 0の検出結果に基づいて方法を選び、どちらの方法で進めるかを明示してください。

---

フェーズ 7 — プレビューをWeaverse Builderに接続する

ユーザーを案内してください。Builderで、プレビューのアドレスバーにあるURLをクリックし、Manage previews（またはBuilder → Project Settings → Manage URLs → Preview URLsセクション）を選択します。http://localhost:3456を追加して、保存してください。

---

フェーズ 8 — 検証（成功の判定基準）

次のチェックがすべて成功するまで、セットアップが成功したと報告しないでください。

curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456   # 200
npm run typecheck                                               # passes

引き継ぎや本番環境の準備の前に、次の完全なチェックを実施することを推奨します。

npm run build

また、ユーザーが確認できる場合は、BuilderでWeaverseのプレビューがconnectedと表示されていることも確認してください。必須のチェックに失敗した場合は、完了を報告する前に修正してください。修正できない場合は、どのチェックに失敗したのかを正確に報告してください。

---

フェーズ 9 — スキルパック一式をインストールする（完了）

最後に、完全なshopify-hydrogen-skillsパックを、すべてのスキルとエージェントを含めて、非対話形式で生成したストアフロントプロジェクト内に（他の場所ではなく）インストールしてください。セットアップの依頼にはこれが明示されているため、インストール自体が必要です。

npx skills@latest add Weaverse/shopify-hydrogen-skills --all

次に、生成された内容を確認してください。

git status --short          # review what the pack install generated

これらの変更の公開は別個の外部への影響であるため、もう一度確認してください。 git statusに表示されるファイル一覧と、コミットメッセージの内容をユーザーに示してから、以下の処理を実行する前に承認を待ってください。

git add -A && git commit -m "Add shopify-hydrogen-skills pack"
git push

ユーザーが断った場合は、インストールしたパックを作業ツリーに残し、未コミットであることを伝えてください。このコミット／プッシュ処理を、無条件で実行してはいけません。

---

全シーケンス（チートシート）

1. 環境を検出します（node、gh+auth、Shopify CLI、パッケージマネージャー）。
2. npx @weaverse/cli@latest create（デフォルトは pilot）でスキャフォールディングし、続けて git init を実行します。
3. 必要に応じて SESSION_SECRET を生成します。
4. デモ用Shopifyストアで起動します（インストール、npm run dev、200を確認）。← ここが見せ場です。
5. ユーザーのストアに切り替えます。Hydrogenアプリをインストール → npx shopify hydrogen link → npx shopify hydrogen env pull → PUBLIC_STORE_DOMAIN と PUBLIC_STOREFRONT_API_TOKEN が実際の値であることを確認してから使用します。
6. リポジトリ名／公開設定／初回のプッシュについて承認を求めてから、リポジトリを作成してプッシュします（承認後に gh repo create を実行し、必要に応じて手動で代替します）。.env／シークレットは絶対にコミットしないでください。
7. Weaverse MCPを設定します（WEAVERSE_API_KEY。ライブ書き込みは WEAVERSE_ENABLE_LIVE_WRITES=true を設定し、同意を得た場合のみ実行します）。
8. BuilderでプレビューURLを接続します（Manage previews）。
9. 必須のチェックを確認します（200 + 型チェック）。引き継ぎ／本番環境への準備時にはビルドを実行します。
10. パック全体をインストールします：npx skills@latest add Weaverse/shopify-hydrogen-skills --all。git status を確認し、コミット／プッシュの前に承認を求めます。

必須変数のクイックリファレンス

変数	レンダリングに必要？	入手元
SESSION_SECRET	はい	エージェントが生成するランダム文字列
PUBLIC_STORE_DOMAIN	はい	Shopify Hydrogenアプリ（env pull）
PUBLIC_STOREFRONT_API_TOKEN	はい	Shopify Hydrogenアプリ（env pull）
WEAVERSE_PROJECT_ID	はい	Weaverse Builder（セットアッププロンプト）
WEAVERSE_API_KEY	MCPのみ	Weaverse Studio → Dashboard → Account/Settings → API Keys
SHOP_ID、customer-account、checkout、storefront-id、analytics	いいえ（機能をすべて利用する場合）	Shopify／後で設定