Shopify Development Skill

このスキルは以下のような場合に使用します:

• Shopify アプリまたはエクステンションの構築
• チェックアウト/管理画面/POS UI のカスタマイズの作成
• Liquid テンプレートを使用したテーマの開発
• Shopify GraphQL または REST API との統合
• ウェブフック またはお支払い機能の実装
• メタフィールドまたは Shopify Functions の操作

---

ROUTING: 何を構築するか

ユーザーが外部サービスを統合したい、または販売者向けツールを構築したい、または機能に対して課金したい場合: → アプリ を構築してください (references/app-development.md を参照)

ユーザーがチェックアウトをカスタマイズしたい、または管理画面 UI を追加したい、または POS アクションを作成したい、または割引ルールを実装したい場合: → エクステンション を構築してください (references/extensions.md を参照)

ユーザーがストアフロント デザインをカスタマイズしたい、または商品/コレクションページを変更したい場合: → テーマ を構築してください (references/themes.md を参照)

ユーザーがバックエンドロジック とストアフロント UI の両方が必要な場合: → アプリ + テーマエクステンション の組み合わせを構築してください

---

Shopify CLI コマンド

CLI をインストール:

npm install -g @shopify/cli@latest

アプリを作成して実行:

shopify app init          # 新しいアプリを作成
shopify app dev           # トンネル付きの開発サーバーを起動
shopify app deploy        # ビルドして Shopify にアップロード

エクステンションを生成:

shopify app generate extension --type checkout_ui_extension
shopify app generate extension --type admin_action
shopify app generate extension --type admin_block
shopify app generate extension --type pos_ui_extension
shopify app generate extension --type function

テーマ開発:

shopify theme init        # 新しいテーマを作成
shopify theme dev         # localhost:9292 でローカルプレビューを起動
shopify theme pull --live # ライブテーマをプル
shopify theme push --development  # 開発テーマにプッシュ

---

アクセススコープ

shopify.app.toml で設定:

[access_scopes]
scopes = "read_products,write_products,read_orders,write_orders,read_customers"

一般的なスコープ:

• read_products, write_products - 商品カタログへのアクセス
• read_orders, write_orders - 注文管理
• read_customers, write_customers - 顧客データ
• read_inventory, write_inventory - 在庫レベル
• read_fulfillments, write_fulfillments - 注文フルフィルメント

---

GraphQL パターン (API 2026-01 に対して検証済み)

商品をクエリ

query GetProducts($first: Int!, $query: String) {
  products(first: $first, query: $query) {
    edges {
      node {
        id
        title
        handle
        status
        variants(first: 5) {
          edges {
            node {
              id
              price
              inventoryQuantity
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

注文をクエリ

query GetOrders($first: Int!) {
  orders(first: $first) {
    edges {
      node {
        id
        name
        createdAt
        displayFinancialStatus
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
      }
    }
  }
}

メタフィールドを設定

mutation SetMetafields($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields {
      id
      namespace
      key
      value
    }
    userErrors {
      field
      message
    }
  }
}

変数の例:

{
  "metafields": [
    {
      "ownerId": "gid://shopify/Product/123",
      "namespace": "custom",
      "key": "care_instructions",
      "value": "Handle with care",
      "type": "single_line_text_field"
    }
  ]
}

---

チェックアウトエクステンションの例

import {
  reactExtension,
  BlockStack,
  TextField,
  Checkbox,
  useApplyAttributeChange,
} from "@shopify/ui-extensions-react/checkout";

export default reactExtension("purchase.checkout.block.render", () => (
  <GiftMessage />
));

function GiftMessage() {
  const [isGift, setIsGift] = useState(false);
  const [message, setMessage] = useState("");
  const applyAttributeChange = useApplyAttributeChange();

  useEffect(() => {
    if (isGift && message) {
      applyAttributeChange({
        type: "updateAttribute",
        key: "gift_message",
        value: message,
      });
    }
  }, [isGift, message]);

  return (
    <BlockStack spacing="loose">
      <Checkbox checked={isGift} onChange={setIsGift}>
        This is a gift
      </Checkbox>
      {isGift && (
        <TextField
          label="Gift Message"
          value={message}
          onChange={setMessage}
          multiline={3}
        />
      )}
    </BlockStack>
  );
}

---

Liquid テンプレートの例

{% comment %} Product Card Snippet {% endcomment %}
<div class="product-card">
  <a href="{{ product.url }}">
    {% if product.featured_image %}
      <img
        src="{{ product.featured_image | img_url: 'medium' }}"
        alt="{{ product.title | escape }}"
        loading="lazy"
      >
    {% endif %}
    <h3>{{ product.title }}</h3>
    <p class="price">{{ product.price | money }}</p>
    {% if product.compare_at_price > product.price %}
      <p class="sale-badge">Sale</p>
    {% endif %}
  </a>
</div>

---

ウェブフック設定

shopify.app.toml 内:

[webhooks]
api_version = "2026-01"

[[webhooks.subscriptions]]
topics = ["orders/create", "orders/updated"]
uri = "/webhooks/orders"

[[webhooks.subscriptions]]
topics = ["products/update"]
uri = "/webhooks/products"

# GDPR 必須ウェブフック (アプリ承認に必須)
[webhooks.privacy_compliance]
customer_data_request_url = "/webhooks/gdpr/data-request"
customer_deletion_url = "/webhooks/gdpr/customer-deletion"
shop_deletion_url = "/webhooks/gdpr/shop-deletion"

---

ベストプラクティス

API 使用方法

• 新開発では REST より GraphQL を使用
• 必要なフィールドのみをリクエスト (クエリコストを削減)
• pageInfo.endCursor を使用したカーソルベースのページネーションを実装
• 250 項目以上の処理にはバルク操作を使用
• 指数バックオフでレート制限に対応

セキュリティ

• API 認証情報を環境変数に保存
• 処理前に常にウェブフック HMAC 署名を検証
• OAuth の state パラメーターを検証して CSRF を防止
• 最小限のアクセススコープをリクエスト
• 埋め込みアプリにはセッショントークンを使用

パフォーマンス

• データが頻繁に変わらない場合は API レスポンスをキャッシュ
• エクステンション内で遅延読み込みを使用
• テーマ内の画像を img_url フィルターで最適化
• レスポンスヘッダーで GraphQL クエリコストを監視

---

トラブルシューティング

レート制限エラーが表示される場合: → 指数バックオフ再試行ロジックを実装 → 大規模データセットにはバルク操作に切り替え → X-Shopify-Shop-Api-Call-Limit ヘッダーを監視

認証に失敗する場合: → アクセストークンがまだ有効であることを確認 → 必要なスコープがすべて付与されたことを確認 → OAuth フローが正常に完了したことを確認

エクステンションが表示されない場合: → エクステンションターゲットが正しいことを確認 → shopify app deploy でエクステンションが公開されたことを確認 → アプリがテストストアにインストールされていることを確認

ウェブフックがイベントを受け取らない場合: → ウェブフック URL が公開でアクセス可能であることを確認 → HMAC 署名検証ロジックを確認 → Partner Dashboard でウェブフックログを確認

GraphQL クエリが失敗する場合: → GraphiQL エクスプローラーを使用してスキーマに対してクエリを検証 → エラーメッセージで非推奨フィールドを確認 → 必要なアクセススコープがあることを確認

---

参照ファイル

詳細な実装ガイドは以下のファイルをお読みください:

• references/app-development.md - OAuth 認証フロー、商品/注文/お支払い機能の GraphQL ミューテーション、ウェブフックハンドラー、お支払い機能 API 統合
• references/extensions.md - チェックアウト UI コンポーネント、管理画面 UI エクステンション、POS エクステンション、割引/支払い/配送用 Shopify Functions
• references/themes.md - Liquid 構文リファレンス、テーマディレクトリ構造、セクションとスニペット、一般的なパターン

---

スクリプト

• scripts/shopify_init.py - インタラクティブプロジェクトスキャフォールディング。実行: python scripts/shopify_init.py
• scripts/shopify_graphql.py - クエリテンプレート、ページネーション、レート制限付き GraphQL ユーティリティ。インポート: from shopify_graphql import ShopifyGraphQL

---

公式ドキュメントリンク

• Shopify Developer Docs: https://shopify.dev/docs
• GraphQL Admin API Reference: https://shopify.dev/docs/api/admin-graphql
• Shopify CLI Reference: https://shopify.dev/docs/api/shopify-cli
• Polaris Design System: https://polaris.shopify.com

API Version: 2026-01 (四半期ごとのリリース、12 ヶ月の廃止予定期間)

使用する場合

このスキルは概要で説明されているワークフローまたはアクションを実行する場合に適用されます。

制限事項

• このスキルは上記で説明されたスコープに明確に合致するタスクの場合にのみ使用してください。
• 出力を環境固有の検証、テスト、または専門家のレビューの代わりとして扱わないでください。
• 必要な入力、パーミッション、安全境界、または成功基準が不足している場合は、停止して明確にしてください。