Shopify App React Router — Development Skill

Overview

This skill provides end-to-end guidance for building Shopify embedded apps using:

• @shopify/shopify-app-react-router v1.x (latest)
• React Router v7 (framework mode)
• Shopify Admin API 2026-04
• TypeScript

The package wraps authentication (OAuth token exchange, session management), GraphQL Admin API access, webhook verification, billing, and App Bridge integration for React Router apps.

适用场景与快速判断（When to Use This Skill）

> 本技能用于构建 Shopify 嵌入式应用（Embedded App）。动手前先确认是否真的需要它。

✅ 适合使用（Use this when…）

• 你要开发 嵌入在 Shopify Admin 后台 运行的应用（左侧菜单 + App Bridge 导航）。
• 技术栈为 React Router v7（framework mode）+ TypeScript + Node.js。
• 需要服务端处理 OAuth 登录、Session 管理、Admin GraphQL/REST API 调用、Webhook 校验、订阅计费。
• 需要官方 authenticate.admin / webhook / public 鉴权封装，而非自己手写 OAuth。

❌ 不适合使用（Do NOT use when…）

• 只是想 改店铺主题/页面（用 Liquid）——请用 shopify-liquid / shopify-theme-pro 相关技能。
• 要做 自定义店铺前台（Headless Storefront）——请用 shopify-hydrogen / shopify-storefront-graphql。
• 只想 抓取/分析已有店铺数据（无应用开发）——直接用 Admin API 客户端即可，不需要本套 React Router 脚手架。
• 纯静态/营销页面——普通前端框架即可，无需 Shopify 鉴权。

🔀 替代方案速查（Alternatives）

🚦 触发信号（何时查阅本技能）

当用户/智能体出现以下意图时，应调用本技能（而不是泛泛去搜 Shopify 文档）：
- 「我要做一个 Shopify 后台应用」/「开发嵌入式 App」/「App 要出现在店铺后台左侧菜单」
- 「用 React Router v7 搭 Shopify 应用」/「shopify-app-react-router 怎么用」
- 「怎么接 Shopify Admin API（GraphQL/REST）」/「OAuth 登录 / Session 怎么存」
- 「怎么处理 Webhook 校验」/「怎么做 订阅计费 billing」/「App Bridge 导航怎么配」
- 「应用 部署上线 到 Fly/Railway/Vercel 等」
> 若意图是「改主题/Liquid」「做无头店铺前台」「只查数据」，按上文「❌ 不适合」转对应技能。

快速上手（Quick Start）

前置条件：Node ≥ 18、已创建 Shopify Partner 应用（拿到 API Key / Secret）、一个测试店铺。

# 1) 用官方脚手架创建（含 shopify.server.ts、Prisma、routes 模板）
npm create @shopify/app@latest

# 2) 安装依赖
npm install

# 3) 填写环境变量（.env）
# SHOPIFY_API_KEY=xxx
# SHOPIFY_API_SECRET=xxx
# SHOPIFY_APP_URL=https://<your-tunnel>/  # 开发用 cloudflare tunnel / ngrok

# 4) 本地启动（自带隧道）
npm run dev

# 5) 在 Partner Dashboard 配置 App URL 与 Redirect URL，安装到测试店

最小可运行骨架（核心 3 文件）：
- app/shopify.server.ts —— shopifyApp() 配置（见第 1 节）。
- app/routes/app.tsx —— 后台布局 + AppProvider + authenticate.admin（见第 7 节）。
- app/routes/webhooks.tsx —— Webhook 校验（见第 5 节）。

> 完成这 3 步即可在店铺后台看到应用菜单并调用 Admin API。后续按需在 loader/action 中调用 admin.graphql(...)。

Package Architecture

@shopify/shopify-app-react-router
├── /server          → shopifyApp(), authenticate, unauthenticated, boundary, ApiVersion, LogSeverity
├── /react           → AppProvider (client component for embedded admin UI)
└── /test-helpers    → testConfig() for integration tests

Key Exports (from @shopify/shopify-app-react-router/server)

Key Exports (from @shopify/shopify-app-react-router/react)

1. shopifyApp Configuration

Create /app/shopify.server.ts as the central configuration file:

import {
  ApiVersion,
  LogSeverity,
  shopifyApp,
} from "@shopify/shopify-app-react-router/server";

const shopify = shopifyApp({
  // Required
  apiKey: process.env.SHOPIFY_API_KEY!,
  apiSecretKey: process.env.SHOPIFY_API_SECRET!,
  appUrl: process.env.SHOPIFY_APP_URL!,
  apiVersion: ApiVersion.April26, // 2026-04

  // Optional
  scopes: ["read_products", "write_products", "read_orders"],
  logger: { level: LogSeverity.Debug },
  isEmbeddedApp: true,           // default: true
  distribution: "AppDistribution.AppStore", // or ShopifyAdmin for custom apps

  // Session storage — use Prisma, SQLite, PostgreSQL, MongoDB, Redis, etc.
  sessionStorage: new PrismaSessionStorage(prisma),

  // Billing — optional, for apps with charges
  billing: undefined,

  // Future flags
  future: { v3_authenticatePublic: true },
});

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

ApiVersion Enum (relevant for 2026-04)

ApiVersion.April26  // "2026-04"
ApiVersion.January26 // "2026-01"
ApiVersion.October25 // "2025-10"
// ... etc

2. Authenticate Admin Requests

Basic Pattern (Loader / Action)

import { authenticate } from "~/shopify.server";
import type { LoaderFunctionArgs, ActionFunctionArgs } from "react-router";

// In a loader
export const loader = async ({ request }: LoaderFunctionArgs) => {
  const { admin, session, billing, cors, redirect } =
    await authenticate.admin(request);

  // admin  → { graphql, rest (via shopify-api) }
  // session → { id, shop, accessToken, isOnline, scope, expires }
  // billing → { require, check, cancel, request }
  // cors    → function to wrap cross-origin responses
  // redirect → { adminPath, embedApp }

  return null;
};

// In an action
export const action = async ({ request }: ActionFunctionArgs) => {
  const { admin } = await authenticate.admin(request);
  // ...
};

AdminContext Return Type

After authenticate.admin(request), the returned AdminContext contains:

3. GraphQL Admin API (primary API)

export const action = async ({ request }: ActionFunctionArgs) => {
  const { admin } = await authenticate.admin(request);

  // admin.graphql(query, options) → Response
  const response = await admin.graphql(
    `#graphql
    query GetProducts($first: Int!) {
      products(first: $first) {
        nodes {
          id
          title
          variants(first: 5) {
            nodes { id price sku inventoryQuantity }
          }
        }
      }
    }`,
    {
      variables: { first: 10 },
      // Optional: Retry configuration
      // retries: 2,
    }
  );

  const { data, errors } = await response.json();

  if (errors) {
    console.error("GraphQL errors:", errors);
    return { error: "Query failed" };
  }

  return { products: data.products.nodes };
};

GraphQL Client Details

• URL: https://{shop}/admin/api/2026-04/graphql.json
• Auth: Automatically injected X-Shopify-Access-Token from session
• Return: Standard Response object — call .json() to parse
• #graphql tag: Optional comment for IDE GraphQL syntax highlighting
• Retries: Optional { retries: 2 } for automatic retry on rate limits
• Typed responses: Use @shopify/api-codegen-preset for TypeScript types

Common GraphQL Operations (2026-04)

# Fetch products with variants and inventory
query {
  products(first: 50) {
    nodes {
      id
      title
      handle
      status
      vendor
      productType
      tags
      totalInventory
      variants(first: 50) {
        nodes { id title price sku inventoryQuantity }
      }
    }
  }
}

# Fetch orders with line items
query {
  orders(first: 50, reverse: true) {
    nodes {
      id
      name
      createdAt
      totalPriceSet { shopMoney { amount currencyCode } }
      displayFinancialStatus
      lineItems(first: 20) {
        nodes { title quantity originalUnitPriceSet { shopMoney { amount } } }
      }
    }
  }
}

# Bulk product update
mutation {
  productUpdate(input: { id: "gid://shopify/Product/123", title: "New Title" }) {
    product { id title }
  }
}

4. REST Admin API (via direct fetch)

The package does NOT expose admin.rest() natively in v1. For REST endpoints, use direct fetch with the session access token:

export const action = async ({ request }: ActionFunctionArgs) => {
  const { session } = await authenticate.admin(request);

  // Direct REST call
  const response = await fetch(
    `https://${session.shop}/admin/api/2026-04/orders.json?status=any&limit=250`,
    {
      headers: {
        "X-Shopify-Access-Token": session.accessToken!,
        "Content-Type": "application/json",
      },
    }
  );

  const data = await response.json();
  return { orders: data.orders };
};

REST rate limits (2026-04)

• REST: 2 requests/second (leaky bucket, 40 burst)
• GraphQL: 50 points/second (1 point per query cost)

5. Webhook Handling

// /app/routes/webhooks.tsx (NOT nested under admin layout)
export const action = async ({ request }: ActionFunctionArgs) => {
  const { topic, shop, payload, admin } =
    await authenticate.webhook(request);

  console.log(`Webhook: ${topic} from ${shop}`);

  // Access the webhook body directly
  // payload contains the parsed webhook body

  // Optionally use admin API in the handler
  if (topic === "PRODUCTS_CREATE") {
    // Do something with the product
  }

  return new Response(null, { status: 200 });
};

Common webhook topics (2026-04)

6. Background Jobs (unauthenticated.admin)

For background tasks (cron jobs, queue workers, 3rd-party webhooks):

import { unauthenticated } from "~/shopify.server";

async function processBackgroundJob(shop: string) {
  const { admin } = await unauthenticated.admin(shop);

  const response = await admin.graphql(
    `#graphql
    query { products(first: 10) { nodes { id title } } }
    `,
  );

  // Process data...
}

7. Admin Layout & Route Structure

app/
├── shopify.server.ts       # shopifyApp() config → default export
├── routes/
│   ├── app.tsx             # Admin layout route (auth + AppBridge)
│   ├── app._index.tsx      # Admin home page
│   ├── app.products.tsx    # Product management page
│   ├── app.orders.tsx      # Order management page
│   └── webhooks.tsx        # Webhook handler (outside admin layout)

Admin Layout Route (app/routes/app.tsx)

import { Link, Outlet, useLoaderData, useRouteError } from "react-router";
import { boundary } from "@shopify/shopify-app-react-router/server";
import { AppProvider } from "@shopify/shopify-app-react-router/react";
import { NavMenu } from "@shopify/app-bridge-react";
import { authenticate } from "~/shopify.server";

export const loader = async ({ request }) => {
  await authenticate.admin(request);
  return { apiKey: process.env.SHOPIFY_API_KEY || "" };
};

export default function App() {
  const { apiKey } = useLoaderData();

  return (
    <AppProvider embedded apiKey={apiKey}>
      <NavMenu>
        <Link to="/app" rel="home">Home</Link>
        <Link to="/app/products">Products</Link>
      </NavMenu>
      <Outlet />
    </AppProvider>
  );
}

export function ErrorBoundary() {
  return boundary.error(useRouteError());
}

export const headers = (args) => boundary.headers(args);

8. Session Storage

Prisma + SQLite (default template)

import { PrismaSessionStorage } from "@shopify/shopify-app-session-storage-prisma";
import prisma from "./db.server";

const shopify = shopifyApp({
  // ...
  sessionStorage: new PrismaSessionStorage(prisma),
});

Other adapters

9. Billing (Subscription Charges)

import { BillingInterval } from "@shopify/shopify-app-react-router/server";

// In shopifyApp config:
const shopify = shopifyApp({
  billing: {
    ["My Plan"]: {
      amount: 9.99,
      currencyCode: "USD",
      interval: BillingInterval.Monthly,
      trialDays: 7,
    },
  },
  // ...
});

// In a loader/action:
export const loader = async ({ request }) => {
  const { billing, session } = await authenticate.admin(request);

  // Check if shop has active subscription
  const hasPayment = await billing.check({
    plans: ["My Plan"],
    isTest: true, // During development
  });

  if (!hasPayment) {
    // Redirect to billing page
    const billingUrl = await billing.request({
      plan: "My Plan",
      isTest: true,
    });
    return redirect(billingUrl);
  }

  return { hasPayment };
};

10. Testing

import { testConfig } from "@shopify/shopify-app-react-router/test-helpers";

// In shopify.server.ts:
let config = { apiKey: "...", apiSecretKey: "...", appUrl: "...", apiVersion: ApiVersion.April26 };

if (process.env.SHOPIFY_TESTING) {
  Object.assign(config, testConfig());
}

// For e2e testing with real session storage:
if (process.env.SHOPIFY_TESTING === "e2e") {
  Object.assign(config, testConfig({ sessionStorage }));
}

11. Deployment

• Supported platforms: Any Node.js host (Fly.io, Railway, Render, Heroku, AWS, Cloudflare Workers with nodejs compat)
• Required env vars: SHOPIFY_API_KEY, SHOPIFY_API_SECRET, SHOPIFY_APP_URL
• Database requirement: Session storage needs a persistent database
• Scopes: Configure in shopify.app.toml or Partner Dashboard
• Webhooks: Register in shopify.app.toml or via Partner Dashboard
• GDPR: Implement mandatory webhooks: customers/data_request, customers/redact, shop/redact

12. Top Shopify Admin API 2026-04 Endpoints

Refer to references/admin-api-2026-04.md for the complete reference of commonly used GraphQL queries, mutations, and REST endpoints for the Shopify Admin API 2026-04 version, including product management, order processing, inventory control, customer data, and store configuration.

13. Security Best Practices（安全最佳实践）

> 嵌入式应用直接持有店铺访问令牌，安全是底线。下列为必做项。

13.1 密钥与凭证管理

• SHOPIFY_API_SECRET、accessToken 只能存在于服务端环境变量，绝对不要写进前端代码或通过 API 返回给浏览器。
• 使用 .env（已 gitignore），禁止提交 .env 到仓库；CI/CD 用平台密钥注入。
• 轮换 Secret 时同步更新环境变量与 Partner Dashboard。

13.2 Webhook HMAC 校验（必须）

• 永远走 authenticate.webhook(request)，它会校验 X-Shopify-Hmac-SHA256 头。
• 切勿在 webhook 路由里手动 request.json() 后直接处理——未经校验的请求可能来自伪造源。
• 处理失败返回 401/500 让 Shopify 重试，不要用 200 吞掉错误。

13.3 Session 与令牌安全

• Session Storage 必须持久化且加密传输；生产环境用 PostgreSQL/Redis，不要用内存存储（多实例会丢 session）。
• isOnline session 含用户级令牌，避免长期留存；离线任务用 unauthenticated.admin(shop)。
• APP_UNINSTALLED webhook 中必须删除该 shop 的所有 session，否则存在令牌永久泄露风险。

13.4 最小权限（Scope）

• 只申请业务必需的 scope（只读就别要 write_*），缩小令牌泄露面。
• 上线前在 Partner Dashboard 复核 scope，避免越权被审核拒绝。

13.5 客户端安全

• 浏览器端只拿到 apiKey（公开信息），绝不下发 accessToken。
• 用 boundary.headers() 维持 Shopify 要求的 CSP 头，防止 iframe 被劫持。
• 所有对外接口强制 HTTPS；本地开发隧道也用 HTTPS。

13.6 防滥用

• 对自己暴露的 action/loader 做基础限流与参数校验，避免被恶意调用耗尽 Shopify API 配额。

14. Error Handling & Resilience（错误处理与容错）

> 评测指出原文档在「网络波动 / 限流 / 参数错误」时缺少清晰提示。本节给出可复制的容错模式。

14.1 通用包装器（Loader / Action）

import { authenticate } from "~/shopify.server";

// 统一错误处理包装：区分鉴权失败 / 参数错误 / 限流 / 未知
async function withAdmin<T>(
  request: Request,
  fn: (admin: any, session: any) => Promise<T>
): Promise<Response> {
  try {
    const { admin, session } = await authenticate.admin(request);
    const result = await fn(admin, session);
    return Response.json({ ok: true, data: result });
  } catch (err) {
    const status = (err as any)?.response?.status ?? 500;
    console.error("[shopify-app] request failed:", err);
    return Response.json(
      { ok: false, error: (err as Error).message, code: status },
      { status: status >= 400 && status < 500 ? status : 500 }
    );
  }
}

14.2 GraphQL 错误解析

admin.graphql() 即便业务出错也常返回 HTTP 200，错误在 errors 数组里：

const res = await admin.graphql(query, { variables });
const { data, errors } = await res.json();
if (errors?.length) {
  // errors: [{ message, path, extensions: { code } }]
  // 常见 code: USER_ERROR / THROTTLED / GRAPHQL_VALIDATION_ERROR
  console.error("GraphQL errors:", errors);
  const msg = errors.map((e: any) => e.message).join("; ");
  return Response.json({ ok: false, error: msg }, { status: 422 });
}

14.3 REST 错误处理

const res = await fetch(url, { headers });
if (!res.ok) {
  // 429 = 限流, 401 = token 失效, 422 = 参数/业务错误, 404 = 资源不存在
  const body = await res.text();
  console.error(`REST ${res.status}:`, body);
  return Response.json({ ok: false, error: body, code: res.status }, { status: res.status });
}

14.4 限流（Rate Limit）应对

• GraphQL：50 点/秒。超出返回 extensions.code === "THROTTLED"。
• REST：2 次/秒（漏桶，40 突发）。超量返回 HTTP 429，响应头 Retry-After 给出等待秒数。
• 策略：捕获 429 → 读 Retry-After → 指数退避重试；批量任务用游标分页 + 限速；admin.graphql(query, { retries: 2 }) 开启自动重试。

14.5 网络重试与超时

• 海外 API 偶发抖动：对 fetch 包一层超时（AbortController，建议 10s）与最多 3 次指数退避。
• 开发环境访问 *.myshopify.com / admin/api 需稳定外网；国内网络不稳时优先部署到海外节点或加代理。

14.6 Webhook 失败

• 处理超时或抛错时返回非 200，让 Shopify 自动重试（约 19 次，指数退避）。
• 保证处理 幂等（同一事件可能多次投递）——用 payload.id 去重。

14.7 错误边界

• 后台路由导出 ErrorBoundary 调用 boundary.error(useRouteError())，保证异常页符合 Shopify CSP，不会白屏。

14.8 错误诊断决策树（从哪里查起）

1. 请求直接抛异常 / 重定向登录循环 → 先查 §16「Failed to validate session」：确认 sessionStorage 持久化、appUrl 与回调一致。
2. 返回 HTTP 4xx → REST 看状态码（401 令牌失效 / 422 参数 / 404 资源）；GraphQL 看 errors[].extensions.code（USER_ERROR=参数 / THROTTLED=限流 / VALIDATION=语法）。
3. 返回 429 → 限流，跳 §14.4：读 Retry-After 退避，开启 retries，降频。
4. 偶发超时 / 连不上 → 网络层，跳 §14.5 + §18 国内适配：检查外网/隧道，部署到海外节点或加代理，加 AbortController 超时。
5. Webhook 收不到 / 401 → 跳 §16「Webhook 返回 401」：只能用 authenticate.webhook，不要手动 parse。
6. 页面白屏 / 无法嵌入 → 跳 §16「应用无法嵌入」：确认 boundary.headers() 与 isEmbeddedApp: true。

15. Best Practices（最佳实践）

15.1 项目结构约定

• 集中 shopify.server.ts 导出 authenticate / unauthenticated / sessionStorage。
• 路由按业务域拆分（app.products.tsx、app.orders.tsx）；Webhook 路由 不嵌套 在 admin 布局下。

15.2 游标分页（避免 offset）

query Products($cursor: String) {
  products(first: 50, after: $cursor) {
    pageInfo { hasNextPage endCursor }
    nodes { id title }
  }
}

• 用 pageInfo.endCursor 循环，直到 hasNextPage=false，不要用偏移分页。

15.3 批量操作

• 大批量写入用 Bulk mutation / bulkOperationRunMutation；导入导出用 productImport / CSV。
• 单次 products(first: N) 控制 N，避免单次请求过大触发超时。

15.4 避免过度请求

• 用 GraphQL 精确选择字段，避免 ... on Product { * } 全量拉取。
• 客户端列表缓存 + 服务端按需请求。

15.5 Webhook 幂等

• 所有 webhook handler 用事件 id 做幂等键，防止重复处理导致数据错乱。

15.6 开启 future flags

• future: { v3_authenticatePublic: true } 等，提前适配破坏性变更，减少升级成本。

15.7 测试策略

• 单元测试用 testConfig() 注入假 session；e2e 用 testConfig({ sessionStorage }) 接真库。
• 对 authenticate、graphql、webhook 校验分别写用例。

16. Troubleshooting / 常见问题（FAQ）

16.1 反模式（常见错误与根因）

17. Advanced Scenarios（高级场景）

17.1 App Proxy（应用代理）

• 在店铺前台以 myshopify.com/apps/<your-app> 暴露服务端路由，用 authenticate.public(request) 校验来源，适合主题内嵌区块拉取应用数据。

17.2 后台队列任务

• 用 cron（node-cron / 平台定时器）调 unauthenticated.admin(shop)，处理日报、同步等；注意限流与幂等。

17.3 GDPR Webhook（合规必做）

• 必须实现 customers/data_request、customers/redact、shop/redact：
• customers/data_request：导出该客户数据并返回。
• customers/redact：删除客户 PII。
• shop/redact：应用卸载后删除店铺全部关联数据（含 session）。

17.4 多店铺 / 多 Session

• sessionStorage 以 shop 为键隔离；离线任务用 unauthenticated.admin(shop) 按店铺取令牌。

18. 国内适配指南（China Deployment & Network）

> 评测指出「国内适配性」仅 3.8：内容依赖海外服务、国内需访问国外资源。本节给出可落地的适配建议。

18.1 网络与访问

• Shopify 服务（Partner API、*.myshopify.com、admin/api）均在海外，国内直接访问可能不稳定或被拦截。
• 开发期：用稳定的 HTTPS 隧道（cloudflared / ngrok）暴露本地，SHOPIFY_APP_URL 必须 HTTPS；隧道域名变化后同步更新 Partner Dashboard 的 App URL / Redirect URL。
• 生产期：将应用部署到 海外节点（Fly.io / Railway 美区、AWS us-east-1、Cloudflare 等），让服务端到 Shopify 的调用走海外内网，规避国内出口瓶颈。
• 若必须经由国内出口，可配置出口代理/专线，但需保证令牌传输全程 HTTPS，且代理本身不落盘密钥。

18.2 数据驻留与合规

• Session / 业务数据建议存储在海外或合规区域，避免跨境数据流动带来的合规问题；GDPR webhook（§17.3）必须实现。
• 不要把店铺数据回传国内再做处理，除非已评估数据出境合规。

18.3 依赖与安装

• npm install @shopify/* 需访问 npm 海外源；国内可配置镜像（如 registry.npmmirror.com），但运行时依赖仍走 Shopify 海外 API。
• 构建产物（Docker 镜像）建议提前在海外 CI 构建并推送到可达的镜像仓库。

18.4 面向中国商家的特殊说明

• 如果你已在中国开展 Shopify 业务（服务海外店铺），本技能完全适用；瓶颈主要是网络而非代码。
• 大陆商家直接开店受限，通常服务的是 海外店铺；此时按 18.1–18.3 部署到海外节点即可顺畅运行。