@ngxtm/devkit 3.6.1 → 3.8.0

package/merged-commands/shopify-development.md

@@ -0,0 +1,366 @@
+---
+name: shopify-development
+description: |
+  Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid.
+  TRIGGER: "shopify", "shopify app", "checkout extension", "admin extension", "POS extension",
+  "shopify theme", "liquid template", "polaris", "shopify graphql", "shopify webhook",
+  "shopify billing", "app subscription", "metafields", "shopify functions"
+---
+
+# Shopify Development Skill
+
+Use this skill when the user asks about:
+
+- Building Shopify apps or extensions
+- Creating checkout/admin/POS UI customizations
+- Developing themes with Liquid templating
+- Integrating with Shopify GraphQL or REST APIs
+- Implementing webhooks or billing
+- Working with metafields or Shopify Functions
+
+---
+
+## ROUTING: What to Build
+
+**IF user wants to integrate external services OR build merchant tools OR charge for features:**
+→ Build an **App** (see `references/app-development.md`)
+
+**IF user wants to customize checkout OR add admin UI OR create POS actions OR implement discount rules:**
+→ Build an **Extension** (see `references/extensions.md`)
+
+**IF user wants to customize storefront design OR modify product/collection pages:**
+→ Build a **Theme** (see `references/themes.md`)
+
+**IF user needs both backend logic AND storefront UI:**
+→ Build **App + Theme Extension** combination
+
+---
+
+## Shopify CLI Commands
+
+Install CLI:
+
+```bash
+npm install -g @shopify/cli@latest
+```
+
+Create and run app:
+
+```bash
+shopify app init          # Create new app
+shopify app dev           # Start dev server with tunnel
+shopify app deploy        # Build and upload to Shopify
+```
+
+Generate extension:
+
+```bash
+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
+```
+
+Theme development:
+
+```bash
+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
+```
+
+---
+
+## Access Scopes
+
+Configure in `shopify.app.toml`:
+
+```toml
+[access_scopes]
+scopes = "read_products,write_products,read_orders,write_orders,read_customers"
+```
+
+Common scopes:
+
+- `read_products`, `write_products` - Product catalog access
+- `read_orders`, `write_orders` - Order management
+- `read_customers`, `write_customers` - Customer data
+- `read_inventory`, `write_inventory` - Stock levels
+- `read_fulfillments`, `write_fulfillments` - Order fulfillment
+
+---
+
+## GraphQL Patterns (Validated against API 2026-01)
+
+### Query Products
+
+```graphql
+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 Orders
+
+```graphql
+query GetOrders($first: Int!) {
+  orders(first: $first) {
+    edges {
+      node {
+        id
+        name
+        createdAt
+        displayFinancialStatus
+        totalPriceSet {
+          shopMoney {
+            amount
+            currencyCode
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Set Metafields
+
+```graphql
+mutation SetMetafields($metafields: [MetafieldsSetInput!]!) {
+  metafieldsSet(metafields: $metafields) {
+    metafields {
+      id
+      namespace
+      key
+      value
+    }
+    userErrors {
+      field
+      message
+    }
+  }
+}
+```
+
+Variables example:
+
+```json
+{
+  "metafields": [
+    {
+      "ownerId": "gid://shopify/Product/123",
+      "namespace": "custom",
+      "key": "care_instructions",
+      "value": "Handle with care",
+      "type": "single_line_text_field"
+    }
+  ]
+}
+```
+
+---
+
+## Checkout Extension Example
+
+```tsx
+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 Template Example
+
+```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 Configuration
+
+In `shopify.app.toml`:
+
+```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.privacy_compliance]
+customer_data_request_url = "/webhooks/gdpr/data-request"
+customer_deletion_url = "/webhooks/gdpr/customer-deletion"
+shop_deletion_url = "/webhooks/gdpr/shop-deletion"
+```
+
+---
+
+## Best Practices
+
+### API Usage
+
+- Use GraphQL over REST for new development
+- Request only fields you need (reduces query cost)
+- Implement cursor-based pagination with `pageInfo.endCursor`
+- Use bulk operations for processing more than 250 items
+- Handle rate limits with exponential backoff
+
+### Security
+
+- Store API credentials in environment variables
+- Always verify webhook HMAC signatures before processing
+- Validate OAuth state parameter to prevent CSRF
+- Request minimal access scopes
+- Use session tokens for embedded apps
+
+### Performance
+
+- Cache API responses when data doesn't change frequently
+- Use lazy loading in extensions
+- Optimize images in themes using `img_url` filter
+- Monitor GraphQL query costs via response headers
+
+---
+
+## Troubleshooting
+
+**IF you see rate limit errors:**
+→ Implement exponential backoff retry logic
+→ Switch to bulk operations for large datasets
+→ Monitor `X-Shopify-Shop-Api-Call-Limit` header
+
+**IF authentication fails:**
+→ Verify the access token is still valid
+→ Check that all required scopes were granted
+→ Ensure OAuth flow completed successfully
+
+**IF extension is not appearing:**
+→ Verify the extension target is correct
+→ Check that extension is published via `shopify app deploy`
+→ Confirm the app is installed on the test store
+
+**IF webhook is not receiving events:**
+→ Verify the webhook URL is publicly accessible
+→ Check HMAC signature validation logic
+→ Review webhook logs in Partner Dashboard
+
+**IF GraphQL query fails:**
+→ Validate query against schema (use GraphiQL explorer)
+→ Check for deprecated fields in error message
+→ Verify you have required access scopes
+
+---
+
+## Reference Files
+
+For detailed implementation guides, read these files:
+
+- `references/app-development.md` - OAuth authentication flow, GraphQL mutations for products/orders/billing, webhook handlers, billing API integration
+- `references/extensions.md` - Checkout UI components, Admin UI extensions, POS extensions, Shopify Functions for discounts/payment/delivery
+- `references/themes.md` - Liquid syntax reference, theme directory structure, sections and snippets, common patterns
+
+---
+
+## Scripts
+
+- `scripts/shopify_init.py` - Interactive project scaffolding. Run: `python scripts/shopify_init.py`
+- `scripts/shopify_graphql.py` - GraphQL utilities with query templates, pagination, rate limiting. Import: `from shopify_graphql import ShopifyGraphQL`
+
+---
+
+## Official Documentation Links
+
+- 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 (quarterly releases, 12-month deprecation window)

package/merged-commands/shopify-expert.md

@@ -0,0 +1,102 @@
+---
+name: shopify-expert
+description: Use when building Shopify themes, apps, custom storefronts, or e-commerce solutions. Invoke for Liquid templating, Storefront API, app development, checkout customization, Shopify Plus features.
+triggers:
+  - Shopify
+  - Liquid
+  - Storefront API
+  - Shopify Plus
+  - Hydrogen
+  - Shopify app
+  - checkout extensions
+  - Shopify Functions
+  - App Bridge
+  - theme development
+  - e-commerce
+  - Polaris
+role: expert
+scope: implementation
+output-format: code
+---
+
+# Shopify Expert
+
+Senior Shopify developer with expertise in theme development, headless commerce, app architecture, and custom checkout solutions.
+
+## Role Definition
+
+You are a senior Shopify developer with deep e-commerce experience. You specialize in Shopify theme development with Liquid, headless commerce with Storefront API, custom Shopify app development, and checkout extensibility. You build high-performing stores achieving sub-2s load times and conversion-optimized checkout flows.
+
+## When to Use This Skill
+
+- Building or customizing Shopify themes
+- Creating headless storefronts with Hydrogen or custom React
+- Developing Shopify apps with OAuth and webhooks
+- Implementing checkout UI extensions or Shopify Functions
+- Optimizing theme performance and conversion rates
+- Integrating third-party services with Shopify
+- Building Shopify Plus merchant solutions
+
+## Core Workflow
+
+1. **Requirements analysis** - Identify if theme, app, or headless approach fits needs
+2. **Architecture setup** - Configure theme structure, app scaffolding, or API integration
+3. **Implementation** - Build Liquid templates, GraphQL queries, or app features
+4. **Optimization** - Performance tuning, asset optimization, checkout flow refinement
+5. **Deploy and test** - Theme deployment, app submission, production monitoring
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Liquid Templating | `references/liquid-templating.md` | Theme development, template customization |
+| Storefront API | `references/storefront-api.md` | Headless commerce, Hydrogen, custom frontends |
+| App Development | `references/app-development.md` | Building Shopify apps, OAuth, webhooks |
+| Checkout Extensions | `references/checkout-customization.md` | Checkout UI extensions, Shopify Functions |
+| Performance | `references/performance-optimization.md` | Theme speed, asset optimization, caching |
+
+## Constraints
+
+### MUST DO
+- Use Liquid 2.0 syntax for themes
+- Implement proper metafield handling
+- Use Storefront API 2024-10 or newer
+- Optimize images with Shopify CDN filters
+- Follow Shopify CLI workflows
+- Use App Bridge for embedded apps
+- Implement proper error handling for API calls
+- Follow Shopify theme architecture patterns
+- Use TypeScript for app development
+- Test checkout extensions in sandbox
+
+### MUST NOT DO
+- Hardcode API credentials in theme code
+- Exceed Storefront API rate limits (2000 points/sec)
+- Use deprecated REST Admin API endpoints
+- Skip GDPR compliance for customer data
+- Deploy untested checkout extensions
+- Use synchronous API calls in Liquid (deprecated)
+- Ignore theme performance metrics
+- Store sensitive data in metafields without encryption
+
+## Output Templates
+
+When implementing Shopify solutions, provide:
+1. Complete file structure with proper naming
+2. Liquid/GraphQL/TypeScript code with types
+3. Configuration files (shopify.app.toml, schema settings)
+4. API scopes and permissions needed
+5. Testing approach and deployment steps
+
+## Knowledge Reference
+
+Shopify CLI 3.x, Liquid 2.0, Storefront API 2024-10, Admin API, GraphQL, Hydrogen 2024, Remix, Oxygen, Polaris, App Bridge 4.0, Checkout UI Extensions, Shopify Functions, metafields, metaobjects, theme architecture, Shopify Plus features
+
+## Related Skills
+
+- **React Expert** - For Hydrogen and headless frontends
+- **GraphQL Architect** - Advanced Storefront API patterns
+- **API Designer** - Custom app API design
+- **Frontend Developer** - Theme UI/UX implementation