Back to Details

vtex-io-storefront-react

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Storefront React Components

店面React组件

When this skill applies

本规范适用场景

Use this skill when building shopper-facing React components under the 
react
builder for storefront experiences.
  • Creating product or category UI widgets
  • Building custom banners, forms, and shopper-facing layout pieces
  • Using storefront hooks or context providers
  • Styling components with css-handles
Do not use this skill for:
  • admin pages
  • block registration and render-runtime contracts
  • service runtime or backend route design
  • GraphQL schema design
在
react
构建器下构建面向消费者的React组件用于店面体验时使用本规范。
  • 创建产品或分类UI组件
  • 构建自定义横幅、表单和面向消费者的布局模块
  • 使用店面钩子或上下文提供者
  • 使用css-handles为组件设置样式
本规范不适用场景：
  • 管理后台页面
  • 块注册和render-runtime契约
  • 服务运行时或后端路由设计
  • GraphQL schema设计

Decision rules

决策规则

  • Treat storefront components as browser-facing UI and keep them safe for shopper contexts.
  • Prefer keeping storefront components presentational and props-driven, and move complex data fetching or business logic to hooks or container components.
  • Use 
    vtex.css-handles
    instead of hardcoded global class names.
  • Prefer receiving data through props or documented storefront hooks and contexts such as 
    useProduct
    , 
    useRuntime
    , or 
    useOrderForm
    instead of calling VTEX APIs directly from the browser or using app keys in storefront code.
  • Keep components resilient to loading, empty, and unavailable product or search context.
  • For shopper-facing copy, use message IDs and helpers from the messages infrastructure, as described in 
    vtex-io-messages-and-i18n
    , instead of string literals.
  • Treat storefront components as part of the storefront accessibility surface: use semantic HTML elements such as 
    button
    or 
    a
    instead of clickable 
    div
    s, and ensure important content has appropriate labels or alternative text.
  • When accessing browser globals such as 
    window
    or 
    document
    , guard against server-side execution, for example by using 
    useEffect
    or checking 
    typeof window !== 'undefined'
    .
  • 将店面组件视为面向浏览器的UI，确保其在消费者上下文下安全运行。
  • 优先让店面组件保持展示型、由props驱动，将复杂的数据获取或业务逻辑移到钩子或容器组件中。
  • 使用
    vtex.css-handles
    而非硬编码的全局类名。
  • 优先通过props或官方文档记载的店面钩子和上下文（如
    useProduct
    、
    useRuntime
    、
    useOrderForm
    ）获取数据，不要在浏览器端直接调用VTEX API，也不要在店面代码中使用应用密钥。
  • 确保组件在加载、空数据、产品或搜索上下文不可用的场景下仍能正常运行。
  • 面向消费者的文案要使用消息基础设施提供的消息ID和辅助工具，如
    vtex-io-messages-and-i18n
    中所述，不要使用字符串字面量。
  • 将店面组件视为店面可访问性的一部分：使用语义化HTML元素如
    button
    或
    a
    ，而非可点击的
    div
    ，同时确保重要内容有合适的标签或替代文本。
  • 访问浏览器全局对象如
    window
    或
    document
    时，要做服务端执行防护，比如使用
    useEffect
    或判断
    typeof window !== 'undefined'
    。

Hard constraints

硬性约束

Constraint: Storefront styling must use css-handles

约束：店面样式必须使用css-handles

Storefront components MUST expose styling through 
css-handles
, not arbitrary hardcoded class names.
Why this matters
css-handles are the customization contract for storefront components. Hardcoded or hidden class names make themes harder to extend safely.
Detection
If a storefront component uses arbitrary global class names without css-handles, STOP and expose styling through handles first.
Correct
tsx
const CSS_HANDLES = ['container', 'title'] as const
Wrong
tsx
return <div className="my-random-block-root">...</div>
店面组件必须通过
css-handles
对外暴露样式能力，不得使用任意硬编码的类名。
重要性说明
css-handles是店面组件的自定义契约。硬编码或隐藏的类名会提高主题的安全扩展难度。
检测规则
如果店面组件使用了未通过css-handles定义的任意全局类名，立刻停止开发，先通过handles暴露样式能力。
正确示例
tsx
const CSS_HANDLES = ['container', 'title'] as const
错误示例
tsx
return <div className="my-random-block-root">...</div>

Constraint: Storefront components must remain browser-safe

约束：店面组件必须保持浏览器安全

Storefront React code MUST not depend on Node-only APIs or server-only assumptions.
Why this matters
These components run in the shopper-facing frontend. Server-only dependencies break rendering and create runtime failures in the browser.
Detection
If a component uses Node-only modules, filesystem access, or server runtime assumptions, STOP and redesign it for the browser.
Correct
tsx
return <span>{label}</span>
Wrong
tsx
import fs from 'fs'
店面React代码不得依赖仅Node可用的API或仅服务端可用的假设。
重要性说明
这些组件运行在面向消费者的前端。仅服务端可用的依赖会破坏渲染逻辑，导致浏览器端出现运行时错误。
检测规则
如果组件使用了仅Node可用的模块、文件系统访问能力或服务端运行时假设，立刻停止开发，重新设计为适配浏览器的实现。
正确示例
tsx
return <span>{label}</span>
错误示例
tsx
import fs from 'fs'

Constraint: Shopper-facing strings must be localizable

约束：面向消费者的字符串必须支持本地化

Visible storefront strings MUST use the app i18n pattern instead of hardcoded text.
Why this matters
Storefront UIs run across locales and stores. Hardcoded strings make the component less reusable and less consistent with VTEX IO localization.
Detection
If shopper-visible copy is hardcoded in JSX, STOP and move it to the i18n mechanism.
Correct
tsx
<FormattedMessage id="storefront.cta" />
Wrong
tsx
<span>Buy now</span>
店面中可见的字符串必须使用应用国际化模式，不得使用硬编码文本。
重要性说明
店面UI会在不同地区和不同商店中运行。硬编码字符串会降低组件的可复用性，也不符合VTEX IO的本地化规范。
检测规则
如果消费者可见的文案硬编码在JSX中，立刻停止开发，将其迁移到国际化机制中。
正确示例
tsx
<FormattedMessage id="storefront.cta" />
错误示例
tsx
<span>Buy now</span>

Preferred pattern

推荐模式

Keep storefront components small, props-driven, css-handle-based, and safe for shopper contexts.
Minimal css-handles pattern:
tsx
import { useCssHandles } from 'vtex.css-handles'

const CSS_HANDLES = ['container', 'title'] as const

export function MyComponent() {
  const { handles } = useCssHandles(CSS_HANDLES)

  return (
    <div className={handles.container}>
      <h2 className={handles.title}>...</h2>
    </div>
  )
}
保持店面组件体积小、props驱动、基于css-handles，且在消费者上下文下安全运行。
最小化css-handles实现模式：
tsx
import { useCssHandles } from 'vtex.css-handles'

const CSS_HANDLES = ['container', 'title'] as const

export function MyComponent() {
  const { handles } = useCssHandles(CSS_HANDLES)

  return (
    <div className={handles.container}>
      <h2 className={handles.title}>...</h2>
    </div>
  )
}

Common failure modes

常见错误模式

  • Hardcoding class names instead of using css-handles.
  • Using browser-unsafe dependencies.
  • Hardcoding shopper-visible strings.
  • Fetching data in ad hoc ways instead of using VTEX storefront patterns.
  • Putting complex business logic or heavy data fetching directly inside presentational components instead of using hooks or containers.
  • Using non-semantic clickable elements such as 
    div
    or 
    span
    with 
    onClick
    where a 
    button
    or 
    a
    element should be used.
  • 硬编码类名而非使用css-handles
  • 使用不兼容浏览器的依赖
  • 硬编码面向消费者的字符串
  • 未遵循VTEX店面模式，以临时方式获取数据
  • 将复杂业务逻辑或繁重的数据获取逻辑直接写在展示组件中，而非使用钩子或容器组件
  • 使用非语义化的可点击元素，如绑定了
    onClick
    的
    div
    或
    span
    ，而本应使用
    button
    或
    a
    元素

Review checklist

审核检查清单

  • Is this component truly shopper-facing?
  • Are styles exposed through css-handles?
  • Is the component safe for browser execution?
  • Are visible strings localized?
  • Is the data flow appropriate for a storefront component?
  • 该组件确实是面向消费者的吗？
  • 样式是否通过css-handles对外暴露？
  • 组件是否可在浏览器中安全执行？
  • 可见字符串是否支持本地化？
  • 数据流是否符合店面组件的要求？

Related skills

相关规范

  • vtex-io-render-runtime-and-blocks
     - Use when the main question is block registration and Store Framework wiring
  • vtex-io-messages-and-i18n
     - Use when the main question is how shopper-facing strings should be translated and organized
  • vtex-io-render-runtime-and-blocks
     - 适用于核心问题为块注册和Store Framework接入的场景
  • vtex-io-messages-and-i18n
     - 适用于核心问题为面向消费者的字符串翻译和组织的场景

Reference

参考文档