shopify-built-for-shopify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Built for Shopify Guidelines

Built for Shopify（BFS）指南

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

本技能在开发过程中强制执行Shopify的Built for Shopify（BFS）质量标准，以确保应用达到Shopify应用商店的最高质量要求。

参考链接：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

在评审代码或开发功能时使用此检查表：

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

1. 集成要求

Embedding (MANDATORY)

嵌入（强制要求）

Apps MUST be embedded in the Shopify admin:

html

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

typescript

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

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

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

html

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

typescript

// 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

所有应用核心工作流必须能在Shopify后台内完成：

核心功能无需外部网站
第三方连接设置必须在应用内可访问
应用首页提供简化的监控/报告

Clean Installation

简洁安装

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

liquid

<!-- 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).

对于店铺前端应用，请使用主题应用扩展而非Asset API：

liquid

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

禁止使用Asset API创建、修改或删除主题文件（允许读取）。

2. Performance Requirements

2. 性能要求

Web Vitals Targets (75th percentile)

Web Vitals 指标目标（第75百分位）

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

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

Optimization Strategies

优化策略

typescript

// 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>

typescript

// 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%

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

3. Design Requirements

3. 设计要求

Familiar (Match Shopify Admin)

风格统一（匹配Shopify后台）

Use Polaris web components to match admin styling:

html

<!-- 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)

使用Polaris Web组件以匹配后台风格：

html

<!-- 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>

需避免的拒绝原因：

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

Navigation

Contextual Save Bar

上下文保存栏

Use for all form inputs:

typescript

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);
  };
  // ...
}

所有表单输入必须使用上下文保存栏：

typescript

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:

html

<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>

使用s-modal并正确使用插槽：

html

<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

4. 友好的用户体验要求

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

错误提示

html

<!-- 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 -->

html

<!-- 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)

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

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

禁止操作	原因
升级倒计时器	给商家造成压力
“不用了，我更喜欢少赚钱”	愧疚/羞辱性语言
自动弹出的模态框/弹窗	分散商家注意力
保证效果（如“提升18%销售额”）	虚假宣传
评价激励（如“五星评价解锁专业版”）	操纵行为
无法关闭的推广内容	给商家造成困扰
类似Shopify的图标/颜色	冒充平台

Premium Features

高级功能

html

<!-- 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

html

<!-- 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可用的功能必须对非Plus商家隐藏（而非仅禁用）

6. Category-Specific Requirements

6. 特定品类要求

If Building: Ads/Analytics/Affiliate Apps

若开发：广告/分析/联盟营销应用

typescript

// 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
  });
});

typescript

// 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

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

If Building: Discount Apps

若开发：折扣应用

graphql

undefined

graphql

undefined

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 } } }

undefined

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

undefined

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

使用Selling Plan API、Subscription Contract API、Customer Payment Method API
在产品页面使用主题应用区块
清晰显示订阅信息（名称、价格、优惠）
使用Customer Account UI扩展进行订阅管理

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

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

If Building: Returns Apps

若开发：退货应用

Sync all return lifecycle events:

returnCreate, reverseDeliveryCreateWithShipping
reverseFulfillmentOrderDispose, returnLineItemRemoveFromReturn
returnCancel, returnClose, refundCreate

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

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

评审Shopify应用代码的BFS合规性时使用：

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

shopify-built-for-shopify

Original

Translation

Built for Shopify Guidelines

Built for Shopify（BFS）指南

Quick Compliance Checklist

快速合规检查表

1. Integration Requirements

1. 集成要求

Embedding (MANDATORY)

嵌入（强制要求）

Primary Workflows

核心工作流

Clean Installation

简洁安装

2. Performance Requirements

2. 性能要求

Web Vitals Targets (75th percentile)

Web Vitals 指标目标（第75百分位）

Optimization Strategies

优化策略

Storefront Performance

店铺前端性能

3. Design Requirements

3. 设计要求

Familiar (Match Shopify Admin)

风格统一（匹配Shopify后台）

Navigation

导航

Contextual Save Bar

上下文保存栏

Modals

模态框

Mobile Responsiveness

移动端响应式设计

4. Helpful UX Requirements

4. 友好的用户体验要求

Onboarding

引导流程

Homepage

首页

Error Messages

错误提示

5. User-Friendly Requirements (No Dark Patterns)

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

Prohibited Practices

禁止行为

Premium Features

高级功能

6. Category-Specific Requirements

6. 特定品类要求

If Building: Ads/Analytics/Affiliate Apps

若开发：广告/分析/联盟营销应用

If Building: Email/SMS Marketing Apps

若开发：邮件/短信营销应用

If Building: Discount Apps

若开发：折扣应用

Use discount functions or native APIs

Use discount functions or native APIs

Do NOT use draft orders for custom discounts

Do NOT use draft orders for custom discounts

Use discountRedeemCodeBulkAdd for multiple codes

Use discountRedeemCodeBulkAdd for multiple codes

If Building: Subscription Apps

若开发：订阅应用

If Building: Fulfillment Apps

若开发：履约应用

If Building: Returns Apps

若开发：退货应用

Code Review Checklist

代码评审检查表

Resources

资源