Shopify App Development

Shopify App Development

Overview

Build Shopify apps using the Shopify CLI 3.x Remix template, which handles OAuth token exchange, session storage, and App Bridge initialization automatically. Embedded apps run inside the Shopify Admin iframe and use Polaris for a native-feeling UI. The modern approach uses the Remix-based @shopify/shopify-app-remix package rather than the legacy Express template.

When to Use This Skill

• When building a public or custom Shopify app that extends Admin functionality
• When creating an embedded app that merchants install from the Shopify App Store
• When implementing OAuth for the first time with session persistence across reinstalls
• When needing to access the Admin API on behalf of authenticated merchants
• When building merchant-facing tooling with Shopify's Polaris design system
• When replacing an older Express/koa-based Shopify app with the modern Remix stack

Core Instructions

1. Scaffold the app with Shopify CLI

   npm install -g @shopify/cli @shopify/theme
   shopify app init my-shopify-app
   # Choose: Remix template
   cd my-shopify-app
   shopify app dev

This scaffolds a Remix app with OAuth, session storage (SQLite by default), and App Bridge already wired up. The dev command tunnels your local server via Cloudflare and installs the app on your Partner development store.

2. Understand the OAuth flow and session handling

The scaffold uses @shopify/shopify-app-remix which handles the OAuth dance. In app/shopify.server.ts:

   import "@shopify/shopify-app-remix/adapters/node";
   import {
     AppDistribution,
     DeliveryMethod,
     shopifyApp,
     LATEST_API_VERSION,
   } from "@shopify/shopify-app-remix/server";
   import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma";
   import { PrismaClient } from "@prisma/client";

   const prisma = new PrismaClient();

   const shopify = shopifyApp({
     apiKey: process.env.SHOPIFY_API_KEY,
     apiSecretKey: process.env.SHOPIFY_API_SECRET || "",
     apiVersion: LATEST_API_VERSION,
     scopes: process.env.SCOPES?.split(","),
     appUrl: process.env.SHOPIFY_APP_URL || "",
     authPathPrefix: "/auth",
     sessionStorage: new PrismaSessionStorage(prisma),
     distribution: AppDistribution.AppStore,
     webhooks: {
       APP_UNINSTALLED: {
         deliveryMethod: DeliveryMethod.Http,
         callbackUrl: "/webhooks",
       },
     },
     hooks: {
       afterAuth: async ({ session }) => {
         shopify.registerWebhooks({ session });
       },
     },
   });

   export default shopify;
   export const authenticate = shopify.authenticate;

3. Protect routes and call the Admin API

Any loader or action that needs Admin API access calls authenticate.admin:

   // app/routes/app._index.tsx
   import { json } from "@remix-run/node";
   import { useLoaderData } from "@remix-run/react";
   import { authenticate } from "../shopify.server";

   export const loader = async ({ request }: LoaderFunctionArgs) => {
     const { admin, session } = await authenticate.admin(request);

     // GraphQL Admin API call
     const response = await admin.graphql(`
       query {
         shop {
           name
           email
           primaryDomain { url }
         }
       }
     `);
     const { data } = await response.json();
     return json({ shop: data.shop });
   };

   export default function Index() {
     const { shop } = useLoaderData<typeof loader>();
     return <Page title={`Hello, ${shop.name}`} />;
   }

4. Build UI with Polaris components

   // app/routes/app.products.tsx
   import {
     Page,
     Layout,
     Card,
     DataTable,
     Button,
     Banner,
   } from "@shopify/polaris";
   import { TitleBar, useAppBridge } from "@shopify/app-bridge-react";

   export default function ProductsPage() {
     const shopify = useAppBridge();

     const handleSave = async () => {
       // Use App Bridge Toast for notifications inside the iframe
       shopify.toast.show("Products updated successfully");
     };

     return (
       <Page>
         <TitleBar title="Products" primaryAction={{ content: "Save", onAction: handleSave }} />
         <Layout>
           <Layout.Section>
             <Card>
               <DataTable
                 columnContentTypes={["text", "numeric", "numeric"]}
                 headings={["Product", "Price", "Inventory"]}
                 rows={[["Widget A", "$19.99", 42]]}
               />
             </Card>
           </Layout.Section>
         </Layout>
       </Page>
     );
   }

5. Configure scopes and handle app reinstallation

Define required scopes in shopify.app.toml:

   name = "my-shopify-app"
   client_id = "your_api_key"
   application_url = "https://your-app.fly.dev"
   embedded = true

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

   [webhooks]
   api_version = "2025-01"

   [[webhooks.subscriptions]]
   topics = ["app/uninstalled"]
   uri = "/webhooks"

Handle the GDPR mandatory webhooks (customers/data_request, customers/redact, shop/redact) even if your app does not store personal data — Shopify requires these endpoints.

6. Deploy to production

   shopify app deploy
   # Deploys to Shopify (functions/extensions)
   # Deploy the Remix server separately (Fly.io, Railway, Render)
   fly launch
   fly deploy

Examples

Mutation via Admin GraphQL API

// Create a product via the Admin API inside a Remix action
export const action = async ({ request }: ActionFunctionArgs) => {
  const { admin } = await authenticate.admin(request);

  const response = await admin.graphql(
    `#graphql
    mutation CreateProduct($input: ProductInput!) {
      productCreate(input: $input) {
        product {
          id
          title
          handle
        }
        userErrors {
          field
          message
        }
      }
    }`,
    {
      variables: {
        input: {
          title: "New Product",
          vendor: "My Store",
          productType: "Widget",
          tags: ["new", "featured"],
        },
      },
    }
  );

  const { data } = await response.json();
  if (data.productCreate.userErrors.length > 0) {
    return json({ errors: data.productCreate.userErrors }, { status: 422 });
  }
  return json({ product: data.productCreate.product });
};

App Bridge Resource Picker (v4)

import { useAppBridge } from "@shopify/app-bridge-react";
import { useState } from "react";
import { Button } from "@shopify/polaris";

export default function ProductSelector() {
  const shopify = useAppBridge();
  const [selected, setSelected] = useState<string[]>([]);

  const handleSelectProducts = async () => {
    const selection = await shopify.resourcePicker({
      type: "product",
      multiple: true,
    });

    if (selection) {
      setSelected(selection.map((p) => p.id));
    }
  };

  return (
    <>
      <Button onClick={handleSelectProducts}>Select Products</Button>
      <p>Selected IDs: {selected.join(", ")}</p>
    </>
  );
}

Best Practices

• Use the Remix CLI template — it handles session storage, CSRF, OAuth token refresh, and frame-ancestor CSP headers automatically
• Store sessions in a persistent database (Prisma + PostgreSQL in production) — the default SQLite storage is unsuitable for multi-instance deployments
• Scope creep hurts conversion — only request the minimum scopes needed; merchants see the scope list during installation
• Use App Bridge for navigation and modals — direct window.location navigation breaks the embedded iframe context
• Validate webhook HMAC signatures — even for mandatory GDPR webhooks that you don't act on
• Test reinstall flows — merchants who uninstall and reinstall must receive fresh OAuth tokens without stale session data
• Use `LATEST_API_VERSION` in development only — pin to a specific version (e.g., 2025-01) in production to avoid breaking changes
• Handle `payment_required` errors — Apps on the App Store may encounter billing requirement errors if merchants exceed their plan

Common Pitfalls

Related Skills

• @shopify-admin-api
• @shopify-webhooks
• @shopify-checkout-extensions
• @shopify-storefront-api
• @oauth-implementation

Build a Product Tagging Page for a Shopify Embedded App

Problem/Feature Description

A Shopify agency is building a bulk product tagging tool for merchants. Merchants need to be able to select products from their store, apply a set of tags to them all at once, and get confirmation feedback — all without leaving the Shopify Admin interface. The tool is a Remix-based embedded app running inside the Shopify Admin iframe.

The UI team has been told to make the tagging page feel like a native part of the Shopify Admin — not a third-party app bolted on. That means using Shopify's own component library throughout, following Shopify's interaction patterns for resource selection and notifications, and navigating between pages in a way that doesn't break the embedded iframe environment. A previous prototype tried using browser-native elements and standard React Router navigation, but merchants reported the page "flickering" and browser alert popups that looked jarring and out of place.

Write the Remix route file for this product tagging page. The page should allow a merchant to open a product picker, display selected products, accept a tag input, submit the tag via a Remix action that calls the Admin GraphQL API, and confirm success to the merchant. The GraphQL mutation and the session authentication should be included.

Output Specification

• app/routes/app.tagging.tsx — the full Remix route with loader, action, and React component for the product tagging page

The file should be complete and self-contained (imports, loader/action, and component all in one file). You may reference ../shopify.server for the authenticate export.

Set Up Webhook Handling for Shopify App Store Submission

Problem/Feature Description

A startup has built a Shopify app that monitors inventory levels and sends alerts to merchants. The app is nearly ready to submit to the Shopify App Store, but the legal and compliance team has flagged that the app doesn't yet meet Shopify's data protection requirements. Shopify requires that every App Store app handles specific data-related webhook topics and can prove its webhook endpoints are authentic — otherwise Shopify will reject the app submission.

The backend engineer needs to write the webhook handler route that covers all required topics. The app stores some merchant and customer data (product watchlists associated with customer emails), so the team needs real logic for the data deletion and redaction topics, not just stubs. In addition, the security architect has pointed out that the current webhook endpoint blindly trusts all incoming requests without verifying they genuinely came from Shopify — this needs to be fixed. Produce a working webhook handler and a WEBHOOK_NOTES.md documenting what was implemented and why each piece is required.

Output Specification

Produce the following files:

• app/routes/webhooks.tsx (or app/routes/webhooks.ts) — a Remix action that handles all required Shopify webhook topics and validates request authenticity
• WEBHOOK_NOTES.md — documentation explaining the webhook topics handled, why each is required, and how request authenticity is verified

Input Files

The following file shows the current (incomplete) webhook handler. Extract it before beginning.

=============== FILE: app/routes/webhooks.tsx =============== import { ActionFunctionArgs } from "@remix-run/node"; import { authenticate } from "../shopify.server"; import db from "../db.server";

export const action = async ({ request }: ActionFunctionArgs) => { const { topic, shop, payload } = await authenticate.webhook(request);

switch (topic) { case "APP_UNINSTALLED": await db.session.deleteMany({ where: { shop } }); break; default: throw new Response("Unhandled webhook topic", { status: 404 }); }

return new Response(); }; =============== END FILE ===============

Migrate Shopify App to Multi-Instance Production Configuration

Problem/Feature Description

The engineering team at a growing e-commerce agency has built a Shopify app that currently works fine on a single developer machine, but they're preparing to launch it publicly on the Shopify App Store. During load testing they discovered that when they scaled their hosting to multiple instances, merchants were getting logged out randomly — their sessions were not persisting across instances.

The current app was prototyped quickly using the default development configuration. Now the team needs to harden the server-side configuration for production: persistent cross-instance session storage, a stable API version that won't silently change on them, and a proper root layout that initializes Shopify's UI framework correctly so merchants don't encounter broken interfaces.

Your job is to write the production-ready server configuration file (app/shopify.server.ts) and the Remix root layout file (app/root.tsx) that addresses these concerns. Also provide a short DEPLOYMENT_NOTES.md explaining what changed from the development setup and why, specifically addressing each production concern.

Output Specification

Produce the following files:

• app/shopify.server.ts — the Shopify server configuration module with production-ready session storage and API version settings
• app/root.tsx — the Remix root layout component properly initialized for use in the Shopify Admin
• DEPLOYMENT_NOTES.md — a brief document explaining the production changes made and why the development defaults are not suitable for multi-instance hosting

Input Files

The following files represent the current development-only configuration. Extract them before beginning.

=============== FILE: app/shopify.server.ts.dev =============== import "@shopify/shopify-app-remix/adapters/node"; import { AppDistribution, DeliveryMethod, shopifyApp, LATEST_API_VERSION, } from "@shopify/shopify-app-remix/server"; import { SQLiteSessionStorage } from "@shopify/shopify-app-session-storage-sqlite";

const shopify = shopifyApp({ apiKey: process.env.SHOPIFY_API_KEY, apiSecretKey: process.env.SHOPIFY_API_SECRET || "", apiVersion: LATEST_API_VERSION, scopes: process.env.SCOPES?.split(","), appUrl: process.env.SHOPIFY_APP_URL || "", authPathPrefix: "/auth", sessionStorage: new SQLiteSessionStorage("sessions.db"), distribution: AppDistribution.AppStore, webhooks: { APP_UNINSTALLED: { deliveryMethod: DeliveryMethod.Http, callbackUrl: "/webhooks", }, }, hooks: { afterAuth: async ({ session }) => { shopify.registerWebhooks({ session }); }, }, });

export default shopify; export const authenticate = shopify.authenticate; =============== END FILE ===============

=============== FILE: app/root.tsx.dev =============== import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "@remix-run/react";

export default function App() { return ( <html lang="en"> <head> <meta charSet="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <Meta /> <Links /> </head> <body> <Outlet /> <ScrollRestoration /> <Scripts /> </body> </html> ); } =============== END FILE ===============