Skip to content
decodecodeveloper docs
Storefront → Templates → Commerce

Commerce overview

Configure commerce integrations for the released Blocks 7.x framework.

Commerce apps are server-side integration packages for a Blocks 7.x website. They provide provider loaders, actions, shared commerce types, and, where available, request middleware and UI hooks. They are separate from Studio MCP Apps, which extend Studio's interface, and from a website template, which supplies the storefront implementation.

What's in the box

IntegrationPackageGuide
VTEX@decocms/apps-vtexVTEX
Shopify@decocms/apps-shopifyShopify
Wake@decocms/apps-wakeWake
Transactional email@decocms/apps-resendResend
Shared commerce types@decocms/apps-commerceCommerce types
SEO, fonts, analytics tags@decocms/apps-websiteWebsite app

Configure flow

Install the provider packages your site uses. Editors configure their app blocks in the Site Editor; code registers each installed app with the runtime. Editing an app form does not install its package or provision the provider.

For autoconfiguration, pass the loaded decofile and an explicit registry. Each package exports its own registry entry; @decocms/apps-commerce/registry supplies shared types, not a combined catalogue.

src/setup/apps.ts
import { autoconfigApps, type AppRegistry } from "@decocms/blocks-admin/apps";
import { loadBlocks } from "@decocms/blocks/cms";
import { VTEX_REGISTRY_ENTRY } from "@decocms/apps-vtex/registry";
import * as vtexMod from "@decocms/apps-vtex/mod";
import { SHOPIFY_REGISTRY_ENTRY } from "@decocms/apps-shopify/registry";
import * as shopifyMod from "@decocms/apps-shopify/mod";
 
const APP_REGISTRY: AppRegistry = [
  { ...VTEX_REGISTRY_ENTRY, module: async () => vtexMod },
  { ...SHOPIFY_REGISTRY_ENTRY, module: async () => shopifyMod },
];
 
await autoconfigApps(loadBlocks(), APP_REGISTRY);

Run this module only on the server, after framework setup has loaded the decofile. On TanStack, import it from the Worker entry after ./setup. Static module imports keep provider code available in the production Worker bundle. See Apps.

The registry

Compose APP_REGISTRY from the packages installed by your site. An entry is skipped when its app block is absent. autoconfigApps(blocks, registry) calls the provider's configure function and registers the returned loaders, actions, sections, and middleware.

Manual configuration

Provider convenience initializers require the blocks map passed by createSiteSetup's initPlatform. Some accept only plain-text credentials. Use the registry path when credentials need secret resolution, and follow the provider's 7.x guide rather than mixing setup patterns.

Peer dependencies

The released integrations use React 19 and the Blocks 7.x packages. Install the same framework major and compatible provider versions; retain the resolved versions in your lockfile. Use framework requirements and each package's peer dependencies when upgrading. An @decocms/apps-* wildcard is a package family, not an installable package name.

Layered responsibilities

  • The framework resolves configuration and provides the editor protocol.
  • Provider packages read or mutate the external commerce system.
  • Website code renders products, cart state, and other UI, using the provider's supported hooks or its own server functions.
  • The Site Editor edits saved configuration; Studio provides the workspace hosting that app.

Reference pages

Use the versioned Apps reference for the runtime contract, and these implementation guides for storefront tasks:

See also