vtex-io-render-runtime-and-blocks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Render Runtime & Block Registration

渲染运行时与区块注册

When this skill applies

适用场景

Use this skill when a VTEX IO storefront component needs to be exposed to Store Framework as a block.

Registering components in
```
store/interfaces.json
```
Mapping block names to React components
Defining block composition and allowed children
Reviewing whether a component is correctly wired into theme JSON

Do not use this skill for:

shopper-facing component internals
admin interfaces
backend service or route design
policy modeling

当需要将VTEX IO店面组件作为区块暴露给Store Framework时可使用本指南。

在
```
store/interfaces.json
```
中注册组件
将区块名称映射到React组件
定义区块组合规则和允许的子区块
检查组件是否正确接入主题JSON

以下场景不适用本指南：

面向消费者的组件内部逻辑
管理后台界面
后端服务或路由设计
策略建模

Decision rules

决策规则

Every block visible to Store Framework must be registered in
```
store/interfaces.json
```
.
Keep block names, component mapping, and composition explicit.
The block ID used as the key in
```
store/interfaces.json
```
, for example
```
product-reviews
```
, is the same ID that storefront themes reference under
```
blocks
```
in
```
store/*.json
```
.
The
```
component
```
field should map to the React entry name under
```
react/
```
, such as
```
ProductReviews
```
, or a nested path such as
```
product/ProductReviews
```
when the app structure is hierarchical.
Use
```
composition
```
intentionally when the block needs an explicit child model.
```
children
```
means the component renders nested blocks through
```
props.children
```
, while
```
blocks
```
means the block exposes named block slots controlled by Store Framework.
```
composition
```
is optional. For many simple blocks, declaring
```
component
```
and, when needed,
```
allowed
```
is enough.
Use this skill for the render/runtime contract, and use storefront/admin skills for the component implementation itself.

所有对Store Framework可见的区块都必须在
```
store/interfaces.json
```
中注册。
区块名称、组件映射、组合规则需显式声明。
```
store/interfaces.json
```
中作为键使用的区块ID（例如
```
product-reviews
```
），与店面主题在
```
store/*.json
```
的
```
blocks
```
下引用的ID完全一致。
```
component
```
字段需映射到
```
react/
```
目录下的React入口名称，例如
```
ProductReviews
```
；如果应用结构是层级化的，也可以使用嵌套路径，例如
```
product/ProductReviews
```
。
当区块需要显式的子区块模型时，可按需使用
```
composition
```
配置：
```
children
```
表示组件通过
```
props.children
```
渲染嵌套区块，
```
blocks
```
表示区块暴露由Store Framework控制的命名区块插槽。
```
composition
```
为可选配置。对于多数简单区块，声明
```
component
```
即可，必要时补充
```
allowed
```
配置。
本指南用于规范渲染/运行时契约，组件本身的实现请参考店面/管理后台相关开发指南。

Hard constraints

硬性约束

Constraint: Storefront blocks must be declared in interfaces.json

约束：店区块必须在interfaces.json中声明

Every React component intended for Store Framework use MUST have a corresponding

interfaces.json

entry.

Why this matters

Without the interface declaration, the component cannot be referenced from theme JSON.

Detection

If a storefront React component is intended to be used as a block but has no matching interface entry, STOP and add it first.

Correct

json

{
  "product-reviews": {
    "component": "ProductReviews"
  }
}

Wrong

tsx

// react/ProductReviews.tsx exists with no interfaces.json mapping

所有供Store Framework使用的React组件都必须在

interfaces.json

中有对应的注册条目。

重要性 没有接口声明的话，主题JSON无法引用该组件。

检测规则 如果一个店面React组件需要作为区块使用，但没有匹配的接口注册条目，请立即停止后续操作，先补充注册信息。

正确示例

json

{
  "product-reviews": {
    "component": "ProductReviews"
  }
}

错误示例

tsx

// react/ProductReviews.tsx文件存在，但没有对应的interfaces.json映射

Constraint: Component mapping must resolve to real React entry files

约束：组件映射必须指向真实存在的React入口文件

The

component

field in

interfaces.json

MUST map to a real exported React entry file.

Why this matters

Broken mapping silently disconnects block contracts from implementation.

Detection

If an interface points to a component name with no corresponding React entry file, STOP and fix the mapping.

Correct

json

{
  "product-reviews": {
    "component": "ProductReviews"
  }
}

Wrong

json

{
  "product-reviews": {
    "component": "MissingComponent"
  }
}

interfaces.json

中的

component

字段必须映射到真实导出的React入口文件。

重要性 错误的映射会导致区块契约和实现之间悄无声息地断开连接。

检测规则 如果接口指向的组件名称没有对应的React入口文件，请立即停止后续操作，修复映射关系。

正确示例

json

{
  "product-reviews": {
    "component": "ProductReviews"
  }
}

错误示例

json

{
  "product-reviews": {
    "component": "MissingComponent"
  }
}

Constraint: Block composition must be intentional

约束：区块组合规则必须符合实际逻辑

Composition and allowed child blocks MUST match the component's actual layout and runtime expectations.

Why this matters

Incorrect composition contracts make theme usage brittle and confusing.

Detection

allowed

composition

do not reflect how the component is supposed to receive children, STOP and correct the block contract.

Correct

json

{
  "product-reviews": {
    "component": "ProductReviews",
    "composition": "children",
    "allowed": ["product-review-item"]
  }
}

Wrong

json

{
  "product-reviews": {
    "component": "ProductReviews",
    "composition": "blocks",
    "allowed": []
  }
}

组合规则和允许的子区块必须与组件实际的布局和运行时预期匹配。

重要性 错误的组合契约会导致主题使用过程中容易出错，且难以排查。

检测规则 如果

allowed

或

composition

配置没有反映组件接收子区块的实际逻辑，请立即停止后续操作，修正区块契约。

正确示例

json

{
  "product-reviews": {
    "component": "ProductReviews",
    "composition": "children",
    "allowed": ["product-review-item"]
  }
}

错误示例

json

{
  "product-reviews": {
    "component": "ProductReviews",
    "composition": "blocks",
    "allowed": []
  }
}

Preferred pattern

Common failure modes

常见错误场景

Forgetting to register a storefront component as a block.
Mapping block names to missing React entry files.
Using the wrong composition model.

忘记将店面组件注册为区块
区块名称映射到不存在的React入口文件
使用了错误的组合模型

Review checklist

审查清单

Is the block declared in
```
interfaces.json
```
?
Does the component mapping resolve correctly?
Are composition and allowed children intentional?
Is runtime registration clearly separated from component internals?

区块是否在
```
interfaces.json
```
中声明？
组件映射是否能正确解析？
组合规则和允许的子区块是否符合实际逻辑？
运行时注册逻辑是否与组件内部逻辑清晰分离？

Reference

参考资料

Store Framework - Block and theme context

Store Framework - 区块与主题上下文

vtex-io-render-runtime-and-blocks

Original

Translation

Render Runtime & Block Registration

渲染运行时与区块注册

When this skill applies

适用场景

Decision rules

决策规则

Hard constraints

硬性约束

Constraint: Storefront blocks must be declared in interfaces.json

约束：店区块必须在interfaces.json中声明

Constraint: Component mapping must resolve to real React entry files

约束：组件映射必须指向真实存在的React入口文件

Constraint: Block composition must be intentional

约束：区块组合规则必须符合实际逻辑

Preferred pattern

推荐模式

Common failure modes

常见错误场景

Review checklist

审查清单

Reference

参考资料