Sub-documents

Document Topic

commerce-types.md Schema.org types reference — Product, Offer, PDP, PLP, Analytics

shared-utils.md Shared utilities — HTTP client, GraphQL, fetch, cookie, normalize

app-pattern.md The Deco App Pattern — mod.ts, manifest, runtime, hooks, context

vtex-deep-structure.md VTEX app deep dive — all 141 files, endpoints, data flow

website-app.md Website app — routing, SEO, handlers, matchers, A/B testing

scripts-codegen.md Scripts & codegen — OpenAPI, GraphQL, templates, CI/CD

new-app-guide.md Creating a new app — step-by-step guide with commerce template

deco-cx/apps Architecture

Reference for the deco-cx/apps monorepo — the canonical library of Deco integrations.

Monorepo Overview

apps/ ├── deco.ts # App registry — lists all ~90 apps ├── deno.json # Deno config, import map, tasks ├── scripts/ # Codegen and project scaffolding │ ├── start.ts # OpenAPI/GraphQL codegen + bundle │ └── new.ts # App/MCP template generator ├── utils/ # Shared utilities (all apps can import) ├── commerce/ # Schema.org commerce types + shared loaders ├── website/ # Base website app (routing, SEO, analytics, image) ├── admin/ # Admin widget types ├── compat/ # Legacy compatibility ($live, std) ├── workflows/ # Deco workflow engine ├── vtex/ # VTEX integration (141 files) ├── shopify/ # Shopify integration ├── nuvemshop/ # Nuvemshop integration ├── wake/ # Wake integration ├── wap/ # Wap integration └── (80+ more apps) # AI, analytics, CRM, payments, etc.

The App Pattern

Every app follows the same structure:

{app-name}/ ├── mod.ts # App factory — exports Props, AppContext, state ├── manifest.gen.ts # Auto-generated — registers all blocks ├── runtime.ts # Client-side invoke proxy (optional) ├── middleware.ts # Request middleware (optional) ├── actions/ # Write operations (mutations) ├── loaders/ # Read operations (data fetching) ├── hooks/ # Client-side Preact hooks (optional) ├── sections/ # CMS-renderable UI sections (optional) ├── handlers/ # HTTP request handlers (optional) ├── components/ # Shared Preact components (optional) ├── utils/ # Internal utilities and types │ ├── types.ts # API response/request types │ ├── client.ts # Typed HTTP client definitions │ ├── transform.ts # API → schema.org mapping (commerce apps) │ └── openapi/ # Auto-generated OpenAPI types (optional) ├── workflows/ # Background workflow definitions (optional) └── preview/ # Admin preview UI (optional)

mod.ts Pattern

import manifest, { Manifest } from "./manifest.gen.ts"; import { type App, type AppContext as AC } from "@deco/deco";

export type AppContext = AC<ReturnType<typeof MyApp>>;

export interface Props { account: string; apiKey?: Secret; // ... }

export default function MyApp(props: Props) { const state = { /* clients, config */ }; const app: App<Manifest, typeof state> = { manifest, state }; return app; }

manifest.gen.ts

Auto-generated by Deco. Registers all actions, loaders, handlers, sections, workflows as blocks.

runtime.ts

import { Manifest } from "./manifest.gen.ts"; import { proxy } from "@deco/deco/web"; export const invoke = proxy<Manifest>();

Shared Utils (/utils/ )

File Purpose

http.ts

createHttpClient<T> — typed HTTP client from OpenAPI specs

graphql.ts

createGraphqlClient — typed GraphQL client

fetch.ts

fetchSafe , fetchAPI , retry with exponential backoff, STALE cache headers

cookie.ts

proxySetCookie , getFlagsFromCookies

normalize.ts

removeDirtyCookies , removeNonLatin1Chars

lru.ts

LRU cache implementation

shortHash.ts

SHA-256 string hashing

pool.ts

Resource pool with acquire/release

worker.ts

Web Worker abstraction (Comlink-style)

dataURI.ts

Script-to-data-URI conversion

capitalize.ts

String capitalization

Commerce Module (/commerce/ )

The shared commerce layer — platform-agnostic types and utilities.

commerce/ ├── types.ts # Schema.org types (Product, Offer, BreadcrumbList, etc.) ├── mod.ts # Composes website + platform (vtex/shopify/wake/vnda) ├── manifest.gen.ts ├── loaders/ │ ├── extensions/ # Product page/list/PLP enrichment │ ├── navbar.ts # Navigation loader │ └── product/ # Product query orchestration ├── sections/Seo/ # SEO sections for PDP/PLP └── utils/ ├── filters.ts # parseRange, formatRange ├── constants.ts # DEFAULT_IMAGE placeholder ├── canonical.ts # Canonical URL from breadcrumb ├── productToAnalyticsItem.ts # Product → GA4 AnalyticsItem └── stateByZip.ts # Brazilian state from ZIP code

Key Types (types.ts)

Type Purpose

Product

Schema.org Product with offers, images, variants

ProductGroup

Product with hasVariant[]

Offer / AggregateOffer

Pricing and availability

ProductDetailsPage

PDP data (product + breadcrumb + SEO)

ProductListingPage

PLP data (products + filters + pagination + SEO)

BreadcrumbList

Navigation path

Filter / FilterToggle / FilterRange

Faceted search filters

Suggestion

Autocomplete results

AnalyticsItem

GA4 event item format

SiteNavigationElement

Menu/navbar structure

VTEX App Structure (/vtex/ )

The largest integration (141 files). For detailed VTEX-specific docs, see the deco-apps-vtex-porting and deco-apps-vtex-review skills.

vtex/ ├── actions/ # 43 files across 11 subdirs │ ├── cart/ # 16 actions (addItems, updateItems, updateCoupons, etc.) │ ├── authentication/# 8 actions (signIn, logout, recovery, etc.) │ ├── address/ # 3 (create, update, delete) │ ├── session/ # 3 (create, edit, delete) │ ├── wishlist/ # 2 (add, remove) │ ├── newsletter/ # 2 (subscribe, updateOptIn) │ ├── masterdata/ # 2 (create, update document) │ └── (orders, payment, profile, review, analytics) ├── loaders/ # 50+ files across 15 subdirs │ ├── intelligentSearch/ # 6 (PDP, PLP, productList, suggestions, topSearches, validator) │ ├── legacy/ # 7 (PDP, PLP, productList, suggestions, brands, pageType, related) │ ├── logistics/ # 5 (salesChannel, pickupPoints, stock) │ ├── workflow/ # 2 (product, products) │ └── (address, cart, categories, collections, orders, payment, profile, session, etc.) ├── hooks/ # 5 (context, useCart, useUser, useWishlist, useAutocomplete) ├── utils/ # 31 files │ ├── transform.ts # Canonical VTEX → schema.org mapping (THE key file) │ ├── types.ts # 1320 lines of VTEX API types │ ├── client.ts # SP, VTEXCommerceStable client definitions │ ├── openapi/ # 12 files — auto-generated from VTEX OpenAPI specs │ └── (cookies, segment, intelligentSearch, legacy, vtexId, etc.) └── (middleware, handlers/sitemap, sections/Analytics, workflows, components, preview)

Shopify App Structure (/shopify/ )

shopify/ ├── actions/cart/ # addItems, updateCoupons, updateItems ├── actions/order/ # draftOrderCalculate ├── actions/user/ # signIn, signUp ├── hooks/ # context, useCart, useUser ├── loaders/ # PDP, PLP, ProductList, RelatedProducts, cart, shop, user, proxy └── utils/ ├── admin/ # Admin API queries ├── storefront/ # Storefront API (GraphQL schema + generated types) └── transform.ts # Shopify → schema.org mapping

Website App (/website/ )

Base app that all storefronts use. Handles routing, SEO, analytics, image optimization, and theme.

Key areas:

• handlers/ — Fresh router, proxy, redirect, sitemap

• loaders/ — Pages, fonts, images, redirects, secrets, environment

• sections/ — Analytics (GA, GTM, Pixel), Rendering, SEO

• matchers/ — Audience targeting (device, cookie, date, location, etc.)

• flags/ — A/B testing, multivariate, audience segmentation

Scripts (/scripts/ )

Script Purpose

start.ts

Runs on deno task start — generates OpenAPI types, GraphQL types, bundles

new.ts

Scaffolds new app from template — deno task new

CI/CD (.github/workflows/ )

Workflow Trigger Purpose

ci.yaml

Push/PR Bundle, fmt check, lint, test, bench

release.yaml

Tag push Publish release

releaser.yaml

PR/comment Version bump, tag creation

Relationship: apps → apps-start

deco-cx/apps (Fresh/Deno) @decocms/apps-start (TanStack/Node) ──────────────────────── ───────────────────────────────── vtex/utils/transform.ts → vtex/utils/transform.ts (ported) vtex/utils/types.ts → vtex/utils/types.ts (ported) vtex/loaders/** → vtex/loaders/** + vtex/inline-loaders/** vtex/actions/** → vtex/actions/** (consolidated) vtex/hooks/** → vtex/hooks/** (React + TanStack Query) commerce/types.ts → commerce/types/commerce.ts commerce/utils/** → commerce/utils/** + commerce/sdk/** utils/fetch.ts → Replaced by vtexFetch/vtexFetchWithCookies utils/http.ts → Not needed (no OpenAPI codegen in apps-start) utils/graphql.ts → vtexIOGraphQL in client.ts

Key differences:

• apps-start has no mod.ts / manifest.gen.ts / runtime.ts (no Deco framework)

• apps-start uses configureVtex() instead of app factory pattern

• apps-start loaders are pure async functions, not Deco blocks

• apps-start hooks use @tanstack/react-query instead of @preact/signals

• apps-start has no OpenAPI codegen — uses manual vtexFetch calls