app-shopify-built-for-shopify
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseBuilt 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.
本技能在开发过程中强制执行Shopify的Built for Shopify（BFS）质量标准，以确保应用达到Shopify应用商店的最高质量要求。
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 dismissible1. 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
导航
Use App Bridge nav menu:
html
<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)
使用App Bridge导航菜单：
html
<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>禁止：
- 创建自定义导航菜单
- 在导航项中使用表情符号
- 设置单独的「首页」链接（应用名称应链接至首页）
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. 友好UX要求
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
undefinedgraphql
undefinedUse 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
mutation {
discountRedeemCodeBulkAdd(
discountId: "gid://shopify/DiscountCodeNode/123"
codes: [{ code: "CODE1" }, { code: "CODE2" }]
) {
bulkCreation {
id
}
}
}
undefinedmutation {
discountRedeemCodeBulkAdd(
discountId: "gid://shopify/DiscountCodeNode/123"
codes: [{ code: "CODE1" }, { code: "CODE2" }]
) {
bulkCreation {
id
}
}
}
undefinedIf 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
- 产品页面使用主题应用块
- 清晰展示订阅信息（名称、价格、优惠金额）
- 使用客户账户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