Shopify应用开发合规指南：满足“专为Shopify打造”质量标准

shopify-built-for-shopify by tamiror6/shopify-app-skills

69 周安装量

33 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/tamiror6/shopify-app-skills --skill shopify-built-for-shopify

开发电商性能优化

🇨🇳中文介绍

专为 Shopify 指南打造

此技能在开发过程中强制执行 Shopify 的"专为 Shopify 打造"质量标准，以确保应用满足 Shopify 应用商店的最高质量门槛。

参考：https://shopify.dev/docs/apps/launch/built-for-shopify/requirements

快速合规清单

在审查代码或构建功能时使用此清单：

BFS 合规性审查：
- [ ] 应用嵌入在 Shopify 管理后台中（使用 App Bridge）
- [ ] 使用会话令牌身份验证
- [ ] 主要工作流程保持在 Shopify 管理后台内
- [ ] 无需额外的登录/注册
- [ ] 使用主题应用扩展（而非 Asset API 进行写入操作）
- [ ] 满足 Web Vitals 目标（LCP ≤2.5s, CLS ≤0.1, INP ≤200ms）
- [ ] 使用与后台样式匹配的 Polaris 组件
- [ ] 移动端响应式设计
- [ ] 使用导航菜单（s-app-nav）和上下文保存栏
- [ ] 错误消息为红色、上下文相关且有用
- [ ] 无暗黑模式或施压策略
- [ ] 高级功能已禁用并标记
- [ ] 推广内容可关闭

1. 集成要求

嵌入（强制要求）

应用必须嵌入到 Shopify 管理后台中：

<!-- 添加到每个文档的 <head> 中 -->
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>

// 使用会话令牌身份验证
import { authenticate } from "@shopify/shopify-app-remix/server";

export async function loader({ request }) {
  const { session } = await authenticate.admin(request);
  // ...
}

主要工作流程

所有主要应用工作流程必须能在 Shopify 管理后台内完成：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

Web Vitals 目标（第 75 百分位）

指标	目标	描述
LCP	≤ 2.5s	最大内容绘制
CLS	≤ 0.1	累积布局偏移
INP	≤ 200ms	交互到下一次绘制

// 懒加载重型组件
const HeavyChart = lazy(() => import('./HeavyChart'));

// 使用 React.memo 处理昂贵的渲染
const ExpensiveList = memo(({ items }) => (
  // ...
));

// 使用骨架屏加载器避免布局偏移
<Suspense fallback={<SkeletonPage />}>
  <AppContent />
</Suspense>

不得使 Lighthouse 分数降低超过 10 分
结账请求：p95 ≤ 500ms，失败率 ≤ 0.1%

熟悉感（匹配 Shopify 管理后台）

使用 Polaris Web 组件以匹配后台样式：

<!-- 使用 s-page 进行页面结构布局 -->
<s-page>
  <s-title-bar title="我的页面">
    <s-button slot="primary-action">保存</s-button>
  </s-title-bar>

  <s-layout>
    <s-layout-section>
      <s-card>
        <s-text>卡片中的内容</s-text>
      </s-card>
    </s-layout-section>
  </s-layout>
</s-page>

需要避免的拒绝原因：

自定义按钮颜色（使用 Polaris 默认值）
衬线/手写体字体
非标准背景颜色
内容未放置在卡片容器中
对比度差（必须满足 WCAG 2.1 AA 标准）

使用 App Bridge 导航菜单：

<s-app-nav>
  <s-nav-item href="/dashboard" selected>仪表板</s-nav-item>
  <s-nav-item href="/settings">设置</s-nav-item>
</s-app-nav>

创建自定义导航菜单
在导航项中使用表情符号
设置单独的"主页"链接（应用名称应链接到主页）

对所有表单输入使用：

import { useAppBridge } from "@shopify/app-bridge-react";
import { SaveBar } from "@shopify/app-bridge/actions";

function SettingsForm() {
  const app = useAppBridge();

  const showSaveBar = () => {
    const saveBar = SaveBar.create(app, {
      saveAction: { disabled: false, loading: false },
      discardAction: { disabled: false, loading: false },
    });
    saveBar.dispatch(SaveBar.Action.SHOW);
  };
  // ...
}

使用带有正确插槽的 s-modal：

<s-modal heading="确认操作">
  <p>模态框内容在此</p>
  <s-button slot="secondary-action">取消</s-button>
  <s-button slot="primary-action" variant="primary">确认</s-button>
</s-modal>

移动端响应能力

在移动设备上无水平滚动
内容必须适当换行/堆叠
所有内容均可访问（无隐藏内容，除非有展开机制）

4. 有用的用户体验要求

简洁，引导商家完成设置
完成后可关闭
无需安装额外的应用
对任何商家信息请求需给出合理解释

主题区块/嵌入状态（如适用）
相关指标/分析
动态内容（不仅仅是静态链接）

<!-- 正确：红色、上下文相关、持久显示 -->
<s-text-field
  label="邮箱"
  error="请输入有效的邮箱地址"
/>

<!-- 错误：使用 toast 显示错误 -->
<!-- 错误：使用非红色的错误颜色 -->
<!-- 错误：字段问题使用页面顶部的错误提示 -->

5. 用户友好要求（无暗黑模式）

禁止事项	原因
升级倒计时器	给商家施加压力
"不了，谢谢，我宁愿少卖点"	使用内疚/羞耻性语言
自动出现的模态框/弹出框	分散商家注意力
保证结果（"增加 18% 的销售额"）	虚假宣传
评论激励（"给 Pro 版打 5 星"）	操纵性行为
不可关闭的促销信息	使商家不堪重负
类似 Shopify 的图标/颜色	冒充行为

<!-- 功能必须在视觉上和功能上都处于禁用状态 -->
<s-card>
  <s-text variant="headingMd">高级分析</s-text>
  <s-badge tone="info">专业版计划</s-badge>
  <s-button disabled>查看分析</s-button>
  <s-link url="/upgrade">升级以解锁</s-link>
</s-card>

仅限 Shopify Plus 的功能对于非 Plus 商家必须隐藏（不仅仅是禁用）

6. 特定类别要求

如果构建：广告/分析/联盟营销应用

// 必须使用 Web Pixel 扩展，而非 script 标签
// extensions/web-pixel/src/index.ts
import { register } from "@shopify/web-pixels-extension";

register(({ analytics }) => {
  analytics.subscribe("page_viewed", (event) => {
    // 跟踪事件
  });
});

如果构建：电子邮件/SMS 营销应用

与 Shopify 同步客户数据
通过客户细分操作扩展使用 Shopify 细分
使用 visitors API 识别店铺访客

如果构建：折扣应用

# 使用折扣函数或原生 API
# 请勿使用草稿订单实现自定义折扣
# 使用 discountRedeemCodeBulkAdd 添加多个代码

mutation {
  discountRedeemCodeBulkAdd(
    discountId: "gid://shopify/DiscountCodeNode/123"
    codes: [{ code: "CODE1" }, { code: "CODE2" }]
  ) {
    bulkCreation {
      id
    }
  }
}

如果构建：订阅应用

使用销售计划 API、订阅合约 API、客户支付方式 API
在产品页面使用主题应用区块
清晰显示订阅信息（名称、价格、节省金额）
使用客户账户 UI 扩展进行订阅管理

如果构建：履约应用

等待商家履约请求后再进行履约
在 4 小时内响应履约请求
在 1 小时内响应取消请求
在创建履约后 1 小时内添加物流跟踪信息
完成率 99%，回调成功率 99.9%

如果构建：退货应用

同步所有退货生命周期事件：

returnCreate, reverseDeliveryCreateWithShipping
reverseFulfillmentOrderDispose, returnLineItemRemoveFromReturn
returnCancel, returnClose, refundCreate

在审查 Shopify 应用代码是否符合 BFS 标准时：

技术方面：
- [ ] App Bridge 脚本在 <head> 中
- [ ] 会话令牌身份验证（非 Cookie 身份验证）
- [ ] 主题应用扩展（无 Asset API 写入操作）
- [ ] Web Pixel 扩展（无用于跟踪的 script 标签）
- [ ] 针对应用类别的正确 API 使用

用户界面/用户体验：
- [ ] 全程使用 Polaris 组件
- [ ] 使用 s-app-nav 进行导航
- [ ] 表单使用上下文保存栏
- [ ] 使用带有正确插槽的 s-modal
- [ ] 响应式设计
- [ ] WCAG 2.1 AA 对比度

内容：
- [ ] 无结果保证
- [ ] 无施压策略
- [ ] 可关闭的推广内容
- [ ] 已禁用并标记的高级功能
- [ ] 清晰的错误消息（红色、上下文相关）
- [ ] 有帮助的新手指引
- [ ] 动态主页内容

🇺🇸English

Built for Shopify Guidelines

This skill enforces Shopify's Built for Shopify (BFS) quality standards during development to ensure apps meet the highest quality bar for the Shopify App Store.

Reference: https://shopify.dev/docs/apps/launch/built-for-shopify/requirements

Quick Compliance Checklist

Use this checklist when reviewing code or building features:

BFS Compliance Review:
- [ ] App is embedded in Shopify admin (App Bridge)
- [ ] Uses session token authentication
- [ ] Primary workflows stay within Shopify admin
- [ ] No additional login/signup required
- [ ] Uses theme app extensions (not Asset API for writes)
- [ ] Meets Web Vitals targets (LCP ≤2.5s, CLS ≤0.1, INP ≤200ms)
- [ ] Uses Polaris components matching admin styling
- [ ] Mobile responsive design
- [ ] Uses nav menu (s-app-nav) and contextual save bar
- [ ] Error messages are red, contextual, and helpful
- [ ] No dark patterns or pressure tactics
- [ ] Premium features are disabled and labeled
- [ ] Promotional content is dismissible

1. Integration Requirements

Embedding (MANDATORY)

Apps MUST be embedded in the Shopify admin:

<!-- Add to <head> of every document -->
<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js"></script>



// Use session token authentication
import { authenticate } from "@shopify/shopify-app-remix/server";

export async function loader({ request }) {
  const { session } = await authenticate.admin(request);
  // ...
}

Primary Workflows

All primary app workflows MUST be completable within the Shopify admin:

No external website required for core functionality
Third-party connection settings must be accessible in-app
Simplified monitoring/reporting on app homepage

Clean Installation

For storefront apps, use theme app extensions instead of Asset API:

<!-- extensions/theme-extension/blocks/my-block.liquid -->
{% schema %}
{
  "name": "My App Block",
  "target": "section",
  "settings": []
}
{% endschema %}

Do NOT use Asset API to create, modify, or delete theme files (reading is allowed).

2. Performance Requirements

Web Vitals Targets (75th percentile)

Metric	Target	Description
LCP	≤ 2.5s	Largest Contentful Paint
CLS	≤ 0.1	Cumulative Layout Shift
INP	≤ 200ms	Interaction to Next Paint

Optimization Strategies

// Lazy load heavy components
const HeavyChart = lazy(() => import('./HeavyChart'));

// Use React.memo for expensive renders
const ExpensiveList = memo(({ items }) => (
  // ...
));

// Avoid layout shifts with skeleton loaders
<Suspense fallback={<SkeletonPage />}>
  <AppContent />
</Suspense>

Storefront Performance

Must not reduce Lighthouse score by more than 10 points
Checkout requests: p95 ≤ 500ms, failure rate ≤ 0.1%

3. Design Requirements

Familiar (Match Shopify Admin)

Use Polaris web components to match admin styling:

<!-- Use s-page for page structure -->
<s-page>
  <s-title-bar title="My Page">
    <s-button slot="primary-action">Save</s-button>
  </s-title-bar>
  
  <s-layout>
    <s-layout-section>
      <s-card>
        <s-text>Content in cards</s-text>
      </s-card>
    </s-layout-section>
  </s-layout>
</s-page>

Rejection reasons to avoid:

Custom button colors (use Polaris defaults)
Serif/script fonts
Non-standard background colors
Content not in card containers
Poor contrast (must meet WCAG 2.1 AA)

Navigation

Use App Bridge nav menu:

<s-app-nav>
  <s-nav-item href="/dashboard" selected>Dashboard</s-nav-item>
  <s-nav-item href="/settings">Settings</s-nav-item>
</s-app-nav>

Do NOT:

Create custom navigation menus
Use emojis in nav items
Have separate "Home" link (app name should link to home)

Contextual Save Bar

Use for all form inputs:

import { useAppBridge } from "@shopify/app-bridge-react";
import { SaveBar } from "@shopify/app-bridge/actions";

function SettingsForm() {
  const app = useAppBridge();
  
  const showSaveBar = () => {
    const saveBar = SaveBar.create(app, {
      saveAction: { disabled: false, loading: false },
      discardAction: { disabled: false, loading: false },
    });
    saveBar.dispatch(SaveBar.Action.SHOW);
  };
  // ...
}

Modals

Use s-modal with proper slots:

<s-modal heading="Confirm Action">
  <p>Modal content here</p>
  <s-button slot="secondary-action">Cancel</s-button>
  <s-button slot="primary-action" variant="primary">Confirm</s-button>
</s-modal>

Mobile Responsiveness

No horizontal scrolling on mobile
Content must wrap/stack appropriately
All content accessible (no hidden without expand mechanism)

4. Helpful UX Requirements

Onboarding

Concise, guiding merchants to completion
Dismissible after completion
No requirement to install additional apps
Justify any merchant information requests

Homepage

Must include:

Theme block/embed status (if applicable)
Relevant metrics/analytics
Dynamic content (not just static links)

Error Messages

<!-- CORRECT: Red, contextual, persistent -->
<s-text-field 
  label="Email"
  error="Please enter a valid email address"
/>

<!-- WRONG: Using toast for errors -->
<!-- WRONG: Non-red error colors -->
<!-- WRONG: Top-of-page errors for field issues -->

5. User-Friendly Requirements (No Dark Patterns)

Prohibited Practices

Don't	Why
Countdown timers for upgrades	Pressures merchants
"No thanks, I prefer less sales"	Guilt/shame language
Auto-appearing modals/popovers	Distracts merchants
Guarantee outcomes ("increase sales 18%")	False claims
Review incentives ("5-star for Pro")	Manipulative
Non-dismissible promotions	Overwhelms merchants
Shopify-like icons/colors	Impersonation

Premium Features

<!-- Features must be visually AND functionally disabled -->
<s-card>
  <s-text variant="headingMd">Advanced Analytics</s-text>
  <s-badge tone="info">Pro Plan</s-badge>
  <s-button disabled>View Analytics</s-button>
  <s-link url="/upgrade">Upgrade to unlock</s-link>
</s-card>

Shopify Plus-only features must be hidden (not just disabled) for non-Plus merchants

6. Category-Specific Requirements

If Building: Ads/Analytics/Affiliate Apps

// MUST use Web Pixel extensions, NOT script tags
// extensions/web-pixel/src/index.ts
import { register } from "@shopify/web-pixels-extension";

register(({ analytics }) => {
  analytics.subscribe("page_viewed", (event) => {
    // Track event
  });
});

If Building: Email/SMS Marketing Apps

Sync customer data to/from Shopify
Use Shopify segments via customer segment action extension
Use visitors API for identifying store visitors

If Building: Discount Apps

# Use discount functions or native APIs
# Do NOT use draft orders for custom discounts
# Use discountRedeemCodeBulkAdd for multiple codes

mutation {
  discountRedeemCodeBulkAdd(
    discountId: "gid://shopify/DiscountCodeNode/123"
    codes: [{ code: "CODE1" }, { code: "CODE2" }]
  ) {
    bulkCreation {
      id
    }
  }
}

If Building: Subscription Apps

Use Selling Plan API, Subscription Contract API, Customer Payment Method API
Use theme app blocks for product pages
Display subscription info clearly (name, price, savings)
Use Customer Account UI extensions for subscription management

If Building: Fulfillment Apps

Wait for merchant fulfillment requests before fulfilling
Respond to fulfillment requests within 4 hours
Respond to cancellation requests within 1 hour
Add tracking info within 1 hour of fulfillment creation
99% completion rate, 99.9% callback success rate

If Building: Returns Apps

Sync all return lifecycle events:

returnCreate, reverseDeliveryCreateWithShipping
reverseFulfillmentOrderDispose, returnLineItemRemoveFromReturn
returnCancel, returnClose, refundCreate

Code Review Checklist

When reviewing Shopify app code for BFS compliance:

Technical:
- [ ] App Bridge script in <head>
- [ ] Session token auth (no cookie auth)
- [ ] Theme app extensions (no Asset API writes)
- [ ] Web Pixel extensions (no script tags for tracking)
- [ ] Proper API usage for app category

UI/UX:
- [ ] Polaris components throughout
- [ ] s-app-nav for navigation
- [ ] Contextual save bar for forms
- [ ] s-modal with proper slots
- [ ] Responsive design
- [ ] WCAG 2.1 AA contrast

Content:
- [ ] No outcome guarantees
- [ ] No pressure tactics
- [ ] Dismissible promotional content
- [ ] Disabled + labeled premium features
- [ ] Clear error messages (red, contextual)
- [ ] Helpful onboarding
- [ ] Dynamic homepage content

Resources

Weekly Installs

Repository

tamiror6/shopif…p-skills

GitHub Stars

First Seen

Feb 6, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex63

gemini-cli63

opencode63

github-copilot62

amp59

kimi-cli59

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

122,000 周安装