Storefront React Components

When this skill applies

react

• 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

• admin pages
• block registration and render-runtime contracts
• service runtime or backend route design
• GraphQL schema design

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'

  .

Hard constraints

Constraint: Storefront styling must use css-handles

css-handles

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

return <div className="my-random-block-root">...</div>

Constraint: Storefront components must remain browser-safe

return <span>{label}</span>

import fs from 'fs'

Constraint: Shopper-facing strings must be localizable

<FormattedMessage id="storefront.cta" />

<span>Buy now</span>

Preferred pattern

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.

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?

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

Reference

• Store Framework - Storefront app context, data, and hooks
• CSS Handles - Styling contract for VTEX IO storefront components