deco-site-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sub-documents

子文档

Document	Topic
cms-wiring.md	CMS block system, __resolveType, decofile, pages, redirects, dependency resolution
section-patterns.md	Section conventions, loaders, LoadingFallback, JSDoc for admin, widget types
client-patterns.md	Invoke proxy, islands, signals, analytics, cart/wishlist/user hooks, SDK utilities
app-composition.md	App factory, AppContext, theme, images, routes, matchers, global layout

文档	主题
cms-wiring.md	CMS区块系统、__resolveType、decofile、页面、重定向、依赖解析
section-patterns.md	区块约定、加载器、LoadingFallback、面向管理员的JSDoc、组件类型
client-patterns.md	Invoke代理、Islands、Signals、分析、购物车/心愿单/用户钩子、SDK工具
app-composition.md	应用工厂、AppContext、主题、图片、路由、匹配器、全局布局

Deco Site Patterns

Deco网站模式

Pattern reference for building Deco storefronts. Documents how a site uses the Deco framework and apps ecosystem.

构建Deco店面的模式参考文档，介绍网站如何使用Deco框架与应用生态系统。

Three-Layer Architecture

三层架构

@deco/deco (framework)
  Resolution engine, block system, plugins, hooks, runtime
        |
deco-cx/apps (integrations)
  Commerce types, VTEX/Shopify loaders, website handlers, matchers, analytics
        |
Site repo (storefront)
  Sections, islands, components, SDK, routes, .deco/blocks

The framework resolves blocks. Apps provide commerce and website capabilities. The site wires them together via CMS configuration and custom code.

@deco/deco (framework)
  Resolution engine, block system, plugins, hooks, runtime
        |
deco-cx/apps (integrations)
  Commerce types, VTEX/Shopify loaders, website handlers, matchers, analytics
        |
Site repo (storefront)
  Sections, islands, components, SDK, routes, .deco/blocks

框架负责解析区块。应用提供电商与网站功能。网站通过CMS配置和自定义代码将二者连接起来。

Site File Structure

网站文件结构

my-store/
|-- deno.json               # Imports, tasks, compiler options
|-- fresh.config.ts          # Fresh + Deco plugin registration
|-- manifest.gen.ts          # Auto-generated block registry
|-- fresh.gen.ts             # Auto-generated Fresh manifest (routes + islands)
|-- runtime.ts               # Typed invoke proxy for client-side calls
|-- main.ts                  # Production entry point
|-- dev.ts                   # Dev entry (tailwind + HMR)
|
|-- apps/                    # App registrations
|   |-- site.ts              # Main app: manifest + dependencies (std, commerce)
|   |-- decohub.ts           # Admin hub re-export
|
|-- .deco/blocks/            # CMS content (decofile)
|   |-- site.json            # Root config: global sections, routes, SEO, theme
|   |-- everyone.json        # Flag with route definitions
|   |-- pages-*.json         # Page blocks with sections and variants
|   |-- redirects-*.json     # Individual redirect definitions
|   |-- vtex.json            # VTEX app configuration
|
|-- sections/                # CMS-renderable UI sections
|   |-- ProductRetrofit/     # Product sections (PDP, shelf, search)
|   |-- HeaderRetrofit/      # Header section
|   |-- FooterRetrofit/      # Footer section
|   |-- ImagesRetrofit/      # Banner, carousel, gallery sections
|   |-- Theme/               # Theme section (colors, fonts, CSS vars)
|
|-- islands/                 # Client-side interactive components (hydrated)
|   |-- HeaderRetrofit/      # Header islands (search, drawers)
|   |-- DetailsRetrofit/     # PDP islands (product actions, size selector)
|   |-- CartRetrofit/        # Cart island
|
|-- components/              # Shared Preact components (used by sections + islands)
|   |-- productRetrofit/     # Product card, gallery, details
|   |-- searchRetrofit/      # Search result, filters, sort
|   |-- uiRetrofit/          # Base UI (image, slider, modal, button)
|   |-- minicartRetrofit/    # Cart, cart item, coupon
|
|-- sdk/                     # Client-side utilities
|   |-- useUIRetrofit.ts     # Global UI state (signals)
|   |-- formatRetrofit.ts    # Price formatting
|   |-- analyticsRetrofit.ts # Analytics event dispatch
|   |-- useAddToCart*.ts     # Add to cart logic
|   |-- useLazyLoad.tsx      # IntersectionObserver lazy loading
|
|-- loaders/                 # Site-specific data loaders
|-- actions/                 # Site-specific mutations
|-- matchers/                # Site-specific audience matchers
|-- routes/                  # Fresh routes (_app.tsx, proxy.ts)
|-- static/                  # Static assets

my-store/
|-- deno.json               # 导入、任务、编译器选项
|-- fresh.config.ts          # Fresh + Deco插件注册
|-- manifest.gen.ts          # 自动生成的区块注册表
|-- fresh.gen.ts             # 自动生成的Fresh清单（路由 + Islands）
|-- runtime.ts               # 用于客户端调用的类型化invoke代理
|-- main.ts                  # 生产环境入口文件
|-- dev.ts                   # 开发环境入口（Tailwind + HMR）
|
|-- apps/                    # 应用注册
|   |-- site.ts              # 主应用：清单 + 依赖（std、commerce）
|   |-- decohub.ts           # 管理中心重导出
|
|-- .deco/blocks/            # CMS内容（decofile）
|   |-- site.json            # 根配置：全局区块、路由、SEO、主题
|   |-- everyone.json        # 包含路由定义的标记
|   |-- pages-*.json         # 包含区块和变体的页面配置
|   |-- redirects-*.json     # 独立重定向定义
|   |-- vtex.json            # VTEX应用配置
|
|-- sections/                # 可通过CMS渲染的UI区块
|   |-- ProductRetrofit/     # 产品区块（商品详情页、商品货架、搜索）
|   |-- HeaderRetrofit/      # 头部区块
|   |-- FooterRetrofit/      # 底部区块
|   |-- ImagesRetrofit/      # 横幅、轮播、图库区块
|   |-- Theme/               # 主题区块（颜色、字体、CSS变量）
|
|-- islands/                 # 客户端交互组件（会进行Hydration）
|   |-- HeaderRetrofit/      # 头部Islands（搜索、抽屉）
|   |-- DetailsRetrofit/     # 商品详情页Islands（商品操作、尺寸选择器）
|   |-- CartRetrofit/        # 购物车Island
|
|-- components/              # 共享Preact组件（供区块 + Islands使用）
|   |-- productRetrofit/     # 商品卡片、图库、详情
|   |-- searchRetrofit/      # 搜索结果、筛选器、排序
|   |-- uiRetrofit/          # 基础UI（图片、滑块、模态框、按钮）
|   |-- minicartRetrofit/    # 购物车、购物车商品、优惠券
|
|-- sdk/                     # 客户端工具
|   |-- useUIRetrofit.ts     # 全局UI状态（Signals）
|   |-- formatRetrofit.ts    # 价格格式化
|   |-- analyticsRetrofit.ts # 分析事件分发
|   |-- useAddToCart*.ts     # 加入购物车逻辑
|   |-- useLazyLoad.tsx      # IntersectionObserver懒加载
|
|-- loaders/                 # 网站专属数据加载器
|-- actions/                 # 网站专属变更操作
|-- matchers/                # 网站专属受众匹配器
|-- routes/                  # Fresh路由（_app.tsx、proxy.ts）
|-- static/                  # 静态资源

Key Concepts

核心概念

1. Everything is a Block

1. 一切皆为区块

Sections, loaders, actions, handlers, matchers, and flags are all "blocks" registered in

manifest.gen.ts

. The CMS references them by key (e.g.,

site/sections/ProductRetrofit/ProductDetails.tsx

区块、加载器、动作、处理器、匹配器和标记都在

manifest.gen.ts

中注册为“区块”。CMS通过键值（例如

site/sections/ProductRetrofit/ProductDetails.tsx

）引用它们。

2. CMS Wires Data to Sections

2. CMS将数据连接到区块

The CMS admin creates page configurations stored in

.deco/blocks/pages-*.json

. Each section in a page can have props that reference loaders via

__resolveType

. The framework resolves these before rendering.

CMS管理员创建的页面配置存储在

.deco/blocks/pages-*.json

中。页面中的每个区块可以拥有通过

__resolveType

引用加载器的属性。框架会在渲染前解析这些引用。

3. Islands Bridge Server and Client

3. Islands 连接服务端与客户端

Sections render on the server. Islands are the client-side boundary -- they hydrate and run in the browser. Islands use

invoke

to call server loaders/actions and

@preact/signals

for reactive state.

区块在服务端渲染。Islands是客户端边界——它们会在浏览器中进行Hydration并运行。Islands使用

invoke

调用服务端加载器/动作，并通过

@preact/signals

实现响应式状态管理。

4. Apps Compose Capabilities

4. 应用组合功能

The site's

apps/site.ts

composes the

std

(compatibility) and

commerce

(VTEX/Shopify) apps as dependencies. Each app contributes loaders, actions, and handlers to the manifest.

网站的

apps/site.ts

将

std

（兼容性）和

commerce

（VTEX/Shopify）应用作为依赖进行组合。每个应用都会向清单贡献加载器、动作和处理器。

Skill	Focus
`deco-core-architecture`	Framework internals (engine, blocks, runtime)
`deco-apps-architecture`	Apps monorepo structure (VTEX, Shopify, website)
`deco-start-architecture`	TanStack Start version of the framework
`deco-to-tanstack-migration`	Fresh/Preact to TanStack/React migration
`deco-apps-vtex-porting`	VTEX-specific porting guide

技能	重点
`deco-core-architecture`	框架内部机制（引擎、区块、运行时）
`deco-apps-architecture`	应用单仓库结构（VTEX、Shopify、网站）
`deco-start-architecture`	框架的TanStack Start版本
`deco-to-tanstack-migration`	从Fresh/Preact迁移到TanStack/React
`deco-apps-vtex-porting`	VTEX专属移植指南