Shop Extension Manifest

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cms/src/extensions/resolve.ts
• CONTEXT.md
• packages/cms/README.md
• packages/cms/src/extensions/resolve.test.ts
• apps/storefront/README.md

The Shop Extension Manifest is an optional, declarative per-shop configuration that unifies various customization surfaces within the commerce platform. It acts as a shop-level control mechanism for enabling or disabling features, overriding theme tokens, and defining store-wide defaults for components and blocks.

The manifest is operator-owned and provides coarse-grained control. It is distinct from the Feature Flag system, which handles global rollouts and targeting; however, where both systems govern the same element (such as a Section visibility), the manifest's shop-level setting takes precedence.
Sources: CONTEXT.md:129-142, packages/cms/src/extensions/resolve.ts:69-75

Architecture and Composition

The manifest functions through a pure "resolver" pattern that layers declarative data onto existing platform defaults. It executes no extension code and loads no remote assets, ensuring a secure architectural firewall between the CMS and third-party logic.

The Resolution Logic

The resolveExtensions function takes the shop's manifest and layers it onto five existing resolvers to return a ResolvedExtensions object. This process follows a specific Setting Cascade where higher tiers override lower ones.

This diagram shows how the resolveExtensions function composes shop-specific configurations by layering the manifest over platform defaults.
Sources: packages/cms/src/extensions/resolve.ts:65-88, CONTEXT.md:143-157

Resolution Tiers

1. Platform Default: The built-in baseline for all shops.
2. Store-wide Default: Values set in the manifest's base bucket that apply across all surfaces.
3. Per-Surface Override: Overrides specific to a context like collection or search.
4. Per-Instance Override: Specific settings authored on a CMS block node for a single page.
   Sources: CONTEXT.md:164-173

Key Configurable Surfaces

The manifest provides control over several specific areas of the storefront experience:

Surface	Description	Source Logic
Theme Tokens	Styling scalars (colors, sizes, spacing) applied via CSS properties.	resolveTheme
Chrome Layout	The order and visibility of fixed regions like header and footer.	resolveChromeLayout
Block Availability	Restrictions on which block types can be used or rendered for the shop.	BLOCK_TYPES filter
Component Settings	Defaults for ambient UI components like Product Cards or Build Notifiers.	COMPONENT_SETTINGS
Block Defaults	Store-wide default settings for specific block types (e.g., default grid layout).	blockDefaults map

Sources: packages/cms/src/extensions/resolve.ts:39-63, CONTEXT.md:129-142

Sections and Chrome

Sections represent toggleable regions of the storefront page chrome (e.g., info-bar, header). The manifest can override the visibility and ordering of these sections.

This flow illustrates the precedence logic for section visibility, where the manifest override is the highest authority.
Sources: CONTEXT.md:179-188, packages/cms/src/extensions/resolve.ts:108-117

Build Notifier Configuration

The manifest allows operators to configure the platform's build-notification banner. If unset, it defaults to a dismissable banner at the bottom of the screen.

// From resolve.ts:145-151
const bn = manifest?.buildNotifier;
const buildNotifier = {
    enabled: bn?.enabled ?? true,
    position: bn?.position ?? 'bottom',
    copy: bn?.copy,
    autoReload: bn?.autoReload ?? false,
    dismissable: bn?.dismissable ?? true,
};

Sources: packages/cms/src/extensions/resolve.ts:145-151, packages/cms/src/extensions/resolve.test.ts:114-123

Data Flow and Storage

The manifest is edited within the Customization Hub in the Admin application. This hub provides a tabbed interface for Theme, Components, Blocks, and Sections.

1. Editing: Operators make changes in the Customization Hub.
2. Staging: Changes are saved as a draft CMS document.
3. Publishing: On publish, the manifest is written to the shops table in Convex.
4. Storefront Consumption: The storefront middleware resolves the tenant and the resolveExtensions function produces the final configuration for the render boundary.

Sources: CONTEXT.md:189-199, apps/storefront/README.md:46-55, packages/cms/README.md:105-115

Conclusion

The Shop Extension Manifest serves as the primary configuration bridge between the operator's intent and the storefront's execution. By centralizing theme, layout, and component configuration into a declarative, shop-scoped data structure, it enables multi-tenant customization while maintaining strict architectural boundaries and performance through predictable resolution logic.