shopify-development

Shopify 開発スキル

次のような依頼について質問された場合に、このスキルを使用します。

• Shopify アプリや拡張機能の構築
• チェックアウト／管理画面／POS の UI カスタマイズの作成
• Liquid テンプレートを使ったテーマの開発
• Shopify GraphQL API または REST API との連携
• Webhook や請求機能の実装
• メタフィールドや Shopify Functions の利用

---

ルーティング：構築するもの

外部サービスとの連携、マーチャント向けツールの構築、または機能への課金を希望する場合： → アプリを構築します（references/app-development.md を参照）

チェックアウトのカスタマイズ、管理画面 UI の追加、POS アクションの作成、または割引ルールの実装を希望する場合： → 拡張機能を構築します（references/extensions.md を参照）

ストアフロントのデザインのカスタマイズ、または商品／コレクションページの変更を希望する場合： → テーマを構築します（references/themes.md を参照）

バックエンドロジックとストアフロント UI の両方が必要な場合： → アプリ＋テーマ拡張機能を組み合わせて構築します

---

実行とバージョンの境界

CLI／API のバージョンを固定してください。例は足場作り用のスケッチであり、デプロイ済みアプリでテストされたものではありません。アプリのデプロイ、テーマのアップロード、フルフィルメント、請求、データのエクスポートには、認可されたストア、スコープ、意図した効果が必要です。結果が不明確な変更操作は再試行しないでください。初期化ツールが出力するのは部分的な設定のみで、既存のプロジェクトフォルダーがある場合は処理を拒否します。また、.env ファイルを読み込むのは SHOPIFY_LOAD_ENV_FILES=1 の場合のみです。CLI で生成されたプロジェクトを優先してください。開発用トンネルではエンドポイントが外部に公開されるため、テストデータを使用してください。

Shopify CLI コマンド

CLI をインストールします。

npm install -g @shopify/cli@latest

アプリを作成して実行します。

shopify app init          # Create new app
shopify app dev           # Start dev server with tunnel
shopify app deploy        # Build and upload to 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        # Create new theme
shopify theme dev         # Start local preview at localhost:9292
shopify theme pull --live # Pull live theme
shopify theme push --development  # Push to dev theme

---

アクセススコープ

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"
    }
  ]
}

---

チェックアウト拡張機能の例（レガシー React API）

この React の例は、2026-01 ではなく、以前の拡張機能 API を対象としています。現在の API では、バージョンを固定した CLI で Preact 拡張機能を生成してください。React のフック／コンポーネントと 2026-01 の Web コンポーネントを混在させないでください。このスケッチを使用する前に、チェックが外されたときにギフト属性をクリアし、変更処理の失敗に対応してください。

import {useState, useEffect} from "react";
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 (true) { // Also clear a previously saved message when gift is unchecked
      applyAttributeChange({
        type: "updateAttribute",
        key: "gift_message",
        value: isGift ? 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>

---

Webhook の設定

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 mandatory webhooks (required for app approval)
[[webhooks.subscriptions]]
compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
uri = "/webhooks/privacy"

---

ベストプラクティス

API の使用

• 新規開発では REST より GraphQL を使用します
• 必要なフィールドだけをリクエストします（クエリコストを抑えられます）
• pageInfo.endCursor を使ったカーソルベースのページネーションを実装します
• 250 件を超えるアイテムを処理する場合は一括操作を使用します
• 指数バックオフでレート制限に対処します

セキュリティ

• API 認証情報を環境変数に保存します
• 処理前に必ず Webhook の HMAC 署名を検証します
• CSRF を防ぐため、OAuth の state パラメーターを検証します
• 最小限のアクセススコープをリクエストします
• 埋め込みアプリではセッショントークンを使用します

パフォーマンス

• データが頻繁に変わらない場合は API レスポンスをキャッシュします
• 拡張機能では遅延読み込みを使用します
• img_url フィルターを使ってテーマ内の画像を最適化します
• レスポンスの extensions.cost オブジェクトで GraphQL クエリコストを監視します

---

トラブルシューティング

レート制限エラーが表示された場合： → 指数バックオフによる再試行ロジックを実装します → 大規模なデータセットには一括操作に切り替えます → GraphQL の extensions.cost.throttleStatus を確認します。呼び出し制限のヘッダーは REST 用です

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

拡張機能が表示されない場合： → 拡張機能のターゲットが正しいか確認します → shopify app deploy で拡張機能が公開されているか確認します → テストストアにアプリがインストールされていることを確認します

Webhook がイベントを受信しない場合： → Webhook URL にパブリックからアクセスできるか確認します → HMAC 署名の検証ロジックを確認します → Partner Dashboard で Webhook のログを確認します

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

---

リファレンスファイル

詳細な実装ガイドについては、以下のファイルを参照してください。

• references/app-development.md - OAuth 認証フロー、商品／注文／請求に関する GraphQL ミューテーション、Webhook ハンドラー、請求 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 開発者向けドキュメント：https://shopify.dev/docs
• GraphQL Admin API リファレンス：https://shopify.dev/docs/api/admin-graphql
• Shopify CLI リファレンス：https://shopify.dev/docs/api/shopify-cli
• Polaris デザインシステム：https://polaris.shopify.com

API バージョン：2026-01（四半期ごとのリリース、非推奨化までの期間は12か月）

使用する場合

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

制限事項

• このスキルは、タスクが上記の範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。