shopify-apps

Shopify Apps Development

Expert guidance for building Shopify Apps with modern architecture, authentication patterns, and best practices based on current Shopify documentation.

Core Capabilities

This skill provides expertise in:

1. App Architecture & Setup - Initialize apps, configure authentication, set up development environment
2. GraphQL API Integration - Admin API and Storefront API queries/mutations with proper patterns
3. App Extensions - Build checkout UI extensions, theme extensions, product subscriptions, POS UI extensions
4. Embedded App UI - Create embedded admin interfaces using App Bridge and Polaris
5. Webhooks & Events - Implement webhook handlers, manage event subscriptions
6. App Distribution - Prepare apps for submission, handle billing, manage app listings

Prerequisites & MCP Integration

Shopify Dev MCP Server: This skill assumes the Shopify Dev MCP server is available and connected. The MCP server provides:

• Access to latest Shopify documentation at https://shopify.dev
• Up-to-date API references and examples
• Current best practices and patterns

When documentation is needed, use the MCP server to fetch the latest information from Shopify's official docs.

Quick Start Workflows

Creating a New Shopify App

1. Choose your stack: Remix (recommended), Next.js, or other Node.js framework
2. Initialize with Shopify CLI:

   npm init @shopify/app@latest
   # or
   shopify app init
   

3. Configure OAuth scopes in shopify.app.toml
4. Set up database for storing session tokens and app data
5. Deploy to a publicly accessible URL (required for OAuth)

Authentication Flow

Modern Shopify apps use Session Tokens (for embedded apps) and OAuth (for authorization):

// Session token validation (embedded apps)
import { authenticate } from './shopify.server';

export async function loader({ request }) {
  const { session, admin } = await authenticate.admin(request);
  // session contains shop, accessToken, etc.
}

// OAuth installation flow
// Handled automatically by Shopify App Remix/CLI templates

Key principles:

• Store access tokens securely per shop
• Use session tokens for embedded app requests
• Validate all requests from Shopify
• Handle token expiration gracefully

GraphQL Query Patterns

Admin API queries (for app backend):

const response = await admin.graphql(
  `#graphql
    query getProducts($first: Int!) {
      products(first: $first) {
        edges {
          node {
            id
            title
            handle
            status
          }
        }
      }
    }`,
  { variables: { first: 10 } }
);

const data = await response.json();

Storefront API queries (for customer-facing features):

const response = await fetch(`https://${shop}/api/2024-01/graphql.json`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Shopify-Storefront-Access-Token': storefrontAccessToken,
  },
  body: JSON.stringify({ query, variables }),
});

Best practices:

• Use query cost analysis to avoid rate limits
• Implement pagination for large datasets
• Batch operations when possible
• Cache responses appropriately

App Extensions Development

Checkout UI Extensions

Build custom UI in checkout flow:

// extensions/checkout-ui/src/Checkout.jsx
import {
  reactExtension,
  useApi,
  Banner,
} from '@shopify/ui-extensions-react/checkout';

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

function Extension() {
  const { cost } = useApi();
  
  return (
    <Banner status="info">
      Your order total: {cost.totalAmount.amount}
    </Banner>
  );
}

Extension targets:

• purchase.checkout.block.render - Checkout page
• purchase.checkout.cart-line-item.render-after - After cart items
• purchase.thank-you.block.render - Thank you page

Theme App Extensions

Inject app functionality into themes:

{% comment %} extensions/theme-extension/blocks/app-block.liquid {% endcomment %}
<div class="app-block" {{ block.shopify_attributes }}>
  <h3>{{ block.settings.heading }}</h3>
  <p>{{ block.settings.description }}</p>
</div>

{% schema %}
{
  "name": "App Block",
  "target": "section",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading"
    }
  ]
}
{% endschema %}

Product Subscription Extensions

Enable subscription functionality:

// Configure subscription plans
const subscriptionPlan = {
  name: "Monthly subscription",
  options: {
    deliveryPolicy: {
      interval: "MONTH",
      intervalCount: 1
    },
    pricingPolicy: {
      percentage: 10 // 10% discount
    }
  }
};

Embedded App UI with App Bridge

Initialize App Bridge:

import createApp from '@shopify/app-bridge';

const app = createApp({
  apiKey: process.env.SHOPIFY_API_KEY,
  host: new URLSearchParams(location.search).get('host'),
});

Use Polaris components for consistent UI:

import { Page, Card, Button } from '@shopify/polaris';

function AppPage() {
  return (
    <Page title="Dashboard">
      <Card sectioned>
        <Button primary>Save</Button>
      </Card>
    </Page>
  );
}

Navigation:

import { Redirect } from '@shopify/app-bridge/actions';

const redirect = Redirect.create(app);
redirect.dispatch(Redirect.Action.ADMIN_PATH, '/products');

Webhook Implementation

Register webhooks:

// shopify.server.js or similar
await shopify.webhooks.addHandlers({
  PRODUCTS_CREATE: {
    deliveryMethod: DeliveryMethod.Http,
    callbackUrl: '/webhooks/products/create',
  },
  ORDERS_PAID: {
    deliveryMethod: DeliveryMethod.Http,
    callbackUrl: '/webhooks/orders/paid',
  },
});

Handle webhook requests:

export async function action({ request }) {
  const { topic, shop, payload } = await authenticate.webhook(request);
  
  switch (topic) {
    case 'PRODUCTS_CREATE':
      await handleProductCreate(shop, payload);
      break;
    case 'ORDERS_PAID':
      await handleOrderPaid(shop, payload);
      break;
  }
  
  return new Response();
}

Webhook security:

• Validate HMAC signatures
• Use webhook verification helpers from Shopify libraries
• Respond with 200 OK quickly (process async if needed)
• Implement retry logic for failed processing

App Billing

Implement usage-based or subscription billing:

// Create a subscription charge
const response = await admin.graphql(
  `#graphql
    mutation appSubscriptionCreate($name: String!, $returnUrl: URL!) {
      appSubscriptionCreate(
        name: $name
        returnUrl: $returnUrl
        lineItems: [{
          plan: {
            appRecurringPricingDetails: {
              price: { amount: 10, currencyCode: USD }
              interval: EVERY_30_DAYS
            }
          }
        }]
      ) {
        userErrors {
          field
          message
        }
        confirmationUrl
        appSubscription {
          id
          status
        }
      }
    }`,
  { variables: { name: "Premium Plan", returnUrl: `${appUrl}/billing/callback` } }
);

// Redirect merchant to confirmationUrl for approval

Testing & Development

Local development:

shopify app dev
# Starts local server with tunnel for OAuth

Testing webhooks locally:

shopify app webhooks trigger --topic=products/create

Partner Dashboard testing:

• Use development stores for testing
• Test installation/uninstallation flows
• Verify GDPR webhook handlers

Security Best Practices

1. Validate all requests - Check HMAC signatures and session tokens
2. Scope principle - Request minimum required OAuth scopes
3. Secure storage - Encrypt access tokens, use environment variables
4. HTTPS only - All app URLs must use HTTPS
5. GDPR compliance - Implement mandatory webhooks: customers/data_request, customers/redact, shop/redact
6. Rate limiting - Respect API rate limits, implement exponential backoff
7. Input validation - Sanitize all user inputs, especially in extensions

Common Patterns

Bulk Operations

For processing large datasets:

const bulkOperation = await admin.graphql(
  `#graphql
    mutation {
      bulkOperationRunQuery(
        query: """
        {
          products {
            edges {
              node {
                id
                title
              }
            }
          }
        }
        """
      ) {
        bulkOperation {
          id
          status
        }
      }
    }`
);

// Poll for completion or use webhook

Metafields Management

Store custom data on Shopify resources:

// Create metafield
await admin.graphql(
  `#graphql
    mutation createMetafield($metafields: [MetafieldsSetInput!]!) {
      metafieldsSet(metafields: $metafields) {
        metafields {
          id
          namespace
          key
          value
        }
      }
    }`,
  {
    variables: {
      metafields: [{
        ownerId: productId,
        namespace: "app",
        key: "custom_data",
        value: JSON.stringify({ setting: true }),
        type: "json"
      }]
    }
  }
);

App Proxy

For public-facing app features:

// Configure in Partner Dashboard: /apps/your-app -> App proxy
// Liquid: GET /apps/your-app-slug
// Backend: https://your-app.com/proxy

export async function loader({ request }) {
  const url = new URL(request.url);
  const shop = url.searchParams.get('shop');
  
  // Return HTML/JSON for storefront
  return json({ data: "public data" });
}

Resources & References

This skill includes detailed reference documentation for advanced topics:

• references/advanced_patterns.md - Multi-shop management, advanced GraphQL patterns, extension development, webhook processing, billing patterns, performance optimization, and testing strategies
• references/api_versioning.md - API version management, migration strategies, breaking changes handling, and upgrade planning

When detailed API information or current examples are needed, use the Shopify Dev MCP server to access:

• API References: Latest GraphQL schema, REST API endpoints
• Tutorial Content: Step-by-step guides for specific features
• Code Examples: Current implementation patterns
• Migration Guides: Updates for API version changes

Primary documentation source: https://shopify.dev/docs/apps/build

Version & API Considerations

• Use the latest stable API version (currently 2024-01 or newer)
• Monitor deprecation notices for upcoming changes
• Test against multiple API versions if supporting older merchants
• Use webhooks to stay informed of API updates