vtex-io-render-runtime-and-blocks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Render Runtime & Block Registration

Render Runtime & 块注册

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 exists with no interfaces.json mapping

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

Render Runtime & 块注册

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

参考资料