OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add vtex/skills --skill vtex-io-react-apps
Apply when building React components under react/ or configuring store blocks in store/ for VTEX IO apps. Covers interfaces.json, contentSchemas.json for Site Editor, VTEX Styleguide for admin apps, and css-handles for storefront styling. Use for creating custom storefront components, admin panels, pixel apps, or any frontend development within the VTEX IO react builder ecosystem.
npx skills add vtex/skills --skill vtex-io-react-apps
Use this skill when building VTEX IO frontend apps using the react builder — creating React components that integrate with Store Framework as theme blocks, configuring interfaces.json, setting up contentSchemas.json for Site Editor, and applying styling patterns.
contentSchemas.jsoncss-handles for safe storefront stylingDo not use this skill for:
vtex-io-service-apps instead)vtex-io-graphql-api instead)vtex-io-app-structure instead)interfaces.json (in /store) maps block names to React component files: "component" is the file name in /react (without extension), "allowed" lists child blocks, "composition" controls how children work ("children" or "blocks")./react that re-exports it. The builder resolves "component": "ProductReviews" to react/ProductReviews.tsx.vtex.css-handles for styling (not inline styles, not global CSS).vtex.styleguide — the official VTEX Admin component library. No third-party UI libraries.contentSchemas.json in /store to make component props editable in Site Editor (JSON Schema format). Merchant edits are stored by vtex.pages-graphql under a key that includes the declaring app's MAJOR version (vendor.app@MAJOR.x:template). A major version bump on the declaring app makes those edits invisible to the resolver until they are migrated to the new major with the updateThemeIds mutation in vtex.pages-graphql@2.x — see vtex-io-storefront-theme-versioning.react-intl and the messages builder for i18n — never hardcode user-facing strings.useQuery from react-apollo), never via direct API calls from the browser.Architecture:
Every React component that should be usable as a Store Framework block MUST have a corresponding entry in store/interfaces.json. Without the interface declaration, the block cannot be referenced in theme JSON files.
Why this matters
The store builder resolves block names to React components through interfaces.json. If a component has no interface, it is invisible to Store Framework and will not render on the storefront.
Detection
If a React component in /react is intended for storefront use but has no matching entry in store/interfaces.json, warn the developer. The component will compile but never render.
Correct
Wrong
Admin panel components (apps using the admin builder) MUST use VTEX Styleguide (vtex.styleguide) for UI elements. You MUST NOT use third-party UI libraries like Material UI, Chakra UI, or Ant Design in admin apps.
Why this matters
VTEX Admin has a consistent design language enforced by Styleguide. Third-party UI libraries produce inconsistent visuals, may conflict with the Admin's global CSS, and add unnecessary bundle size. Apps submitted to the VTEX App Store with non-Styleguide admin UIs will fail review.
Detection
If you see imports from @material-ui, @chakra-ui/react, @chakra-ui, antd, or @ant-design in an admin app, warn the developer to use vtex.styleguide instead.
Correct
Wrong
Every Store Framework block component MUST have a root-level export file in the /react directory that matches the component value in interfaces.json. The actual implementation can live in subdirectories, but the root file must exist.
Why this matters
The react builder resolves components by looking for files at the root of /react. If interfaces.json declares "component": "ProductReviews", the builder looks for react/ProductReviews.tsx. Without this root export file, the component will not be found and the block will fail to render.
Detection
If interfaces.json references a component name that does not have a matching file at the root of /react, STOP and create the export file.
Correct
Wrong
Create the React component inside a subdirectory:
Root export file:
Block interface:
Site Editor schema:
Using the component in a Store Framework theme:
@material-ui/core, @chakra-ui/react, or antd conflicts with VTEX Admin's global CSS, produces inconsistent visuals, and will fail App Store review. Use vtex.styleguide instead.fetch() or axios exposes authentication tokens to the client and bypasses CORS restrictions. Use GraphQL queries that resolve server-side via useQuery from react-apollo.messages builder and react-intl for internationalization.interfaces.json references "component": "ProductReviews" but react/ProductReviews.tsx doesn't exist, the block silently fails to render.vtex release major on an app that ships store/contentSchemas.json makes every Site Editor edit ever saved against blocks declared by that app invisible to the resolver until it is migrated to the new major with the updateThemeIds mutation in vtex.pages-graphql@2.x. Use a patch or minor whenever possible, and follow vtex-io-storefront-theme-versioning when a major is unavoidable.store/interfaces.json?interfaces.json component have a root-level export file in /react?vtex.styleguide (no third-party UI libraries)?css-handles for styling?useQuery), not direct API calls?react-intl and the messages builder?contentSchemas.json defined for Site Editor-editable props?store/contentSchemas.json, has the merchant-facing impact of any planned major version bump been reviewed?vtex-io-storefront-theme-versioning — Use when the app ships store/contentSchemas.json and a version change must preserve or migrate Site Editor content.vtex-io-storefront-theme-app — Use when the question is how a consumer theme composes these blocks into pages.{
"product-reviews": {
"component": "ProductReviews",
"composition": "children",
"allowed": ["product-review-item"]
},
"product-review-item": {
"component": "ReviewItem"
}
}// react/ProductReviews.tsx
import ProductReviews from './components/ProductReviews'
export default ProductReviews// react/ProductReviews.tsx
import ProductReviews from './components/ProductReviews'
export default ProductReviews// react/ProductReviews.tsx exists but NO store/interfaces.json entry
// The component compiles fine but cannot be used in any theme.
// Adding <product-reviews /> in a theme JSON will produce:
// "Block 'product-reviews' not found"
import ProductReviews from './components/ProductReviews'
export default ProductReviews// react/admin/ReviewModeration.tsx
import React, { useState } from 'react'
import {
Layout,
PageHeader,
Table,
Button,
Tag,
Modal,
Input,
} from 'vtex.styleguide'
interface Review {
id: string
author: string
rating: number
text: string
status: 'pending' | 'approved' | 'rejected'
}
function ReviewModeration() {
const [reviews, setReviews] = useState<Review[]>([])
const [modalOpen, setModalOpen] = useState(false)
const tableSchema = {
properties: {
author: { title: 'Author', width: 200 },
rating: { title: 'Rating', width: 100 },
text: { title: 'Review Text' },
status: {
title: 'Status',
width: 150,
cellRenderer: ({ cellData }: { cellData: string }) => (
<Tag type={cellData === 'approved' ? 'success' : 'error'}>
{cellData}
</Tag>
),
},
},
}
return (
<Layout fullWidth pageHeader={<PageHeader title="Review Moderation" />}>
<Table
items={reviews}
schema={tableSchema}
density="medium"
/>
</Layout>
)
}
export default ReviewModeration// react/admin/ReviewModeration.tsx
import React from 'react'
import { DataGrid } from '@material-ui/data-grid'
import { Button } from '@material-ui/core'
// Material UI components will look inconsistent in the VTEX Admin,
// conflict with global styles, and inflate bundle size.
// This app will fail VTEX App Store review.
function ReviewModeration() {
return (
<div>
<DataGrid rows={[]} columns={[]} />
<Button variant="contained" color="primary">Approve</Button>
</div>
)
}// react/ProductReviews.tsx — root-level export file
import ProductReviews from './components/ProductReviews/index'
export default ProductReviews// react/components/ProductReviews/index.tsx — actual implementation
import React from 'react'
import { useCssHandles } from 'vtex.css-handles'
const CSS_HANDLES = ['container', 'title', 'list'] as const
interface Props {
title: string
maxReviews: number
}
function ProductReviews({ title, maxReviews }: Props) {
const handles = useCssHandles(CSS_HANDLES)
return (
<div className={handles.container}>
<h2 className={handles.title}>{title}</h2>
{/* ... */}
</div>
)
}
export default ProductReviewsreact/components/ProductReviews/index.tsx exists but
react/ProductReviews.tsx does NOT exist.
The builder cannot find the component.
Error: "Could not find component ProductReviews"// react/components/ProductReviews/index.tsx
import React, { useMemo } from 'react'
import { useQuery } from 'react-apollo'
import { useProduct } from 'vtex.product-context'
import { useCssHandles } from 'vtex.css-handles'
import GET_REVIEWS from '../../graphql/getReviews.graphql'
import ReviewItem from './ReviewItem'
const CSS_HANDLES = [
'reviewsContainer',
'reviewsTitle',
'reviewsList',
'averageRating',
'emptyState',
] as const
interface Props {
title?: string
showAverage?: boolean
maxReviews?: number
}
function ProductReviews({
title = 'Customer Reviews',
showAverage = true,
maxReviews = 10,
}: Props) {
const handles = useCssHandles(CSS_HANDLES)
const productContext = useProduct()
const productId = productContext?.product?.productId
const { data, loading, error } = useQuery(GET_REVIEWS, {
variables: { productId, limit: maxReviews },
skip: !productId,
})
const averageRating = useMemo(() => {
if (!data?.reviews?.length) return 0
const sum = data.reviews.reduce(
(acc: number, review: { rating: number }) => acc + review.rating,
0
)
return (sum / data.reviews.length).toFixed(1)
}, [data])
if (loading) return <div className={handles.reviewsContainer}>Loading...</div>
if (error) return null
return (
<div className={handles.reviewsContainer}>
<h2 className={handles.reviewsTitle}>{title}</h2>
{showAverage && data?.reviews?.length > 0 && (
<div className={handles.averageRating}>
Average: {averageRating} / 5
</div>
)}
{data?.reviews?.length === 0 ? (
<p className={handles.emptyState}>No reviews yet.</p>
) : (
<ul className={handles.reviewsList}>
{data.reviews.map((review: { id: string; author: string; rating: number; text: string }) => (
<ReviewItem key={review.id} review={review} />
))}
</ul>
)}
</div>
)
}
export default ProductReviews{
"product-reviews": {
"component": "ProductReviews",
"composition": "children",
"allowed": ["product-review-form"],
"render": "client"
}
}{
"definitions": {
"ProductReviews": {
"type": "object",
"properties": {
"title": {
"type": "string",
"title": "Section Title",
"description": "Title displayed above the reviews list",
"default": "Customer Reviews"
},
"showAverage": {
"type": "boolean",
"title": "Show average rating",
"default": true
},
"maxReviews": {
"type": "number",
"title": "Maximum reviews",
"default": 10,
"enum": [5, 10, 20, 50]
}
}
}
}
}{
"store.product": {
"children": [
"product-images",
"product-name",
"product-price",
"buy-button",
"product-reviews"
]
},
"product-reviews": {
"props": {
"title": "What Our Customers Say",
"showAverage": true,
"maxReviews": 20
}
}
}