Component Settings Cascade
Relevant source files
The following files were used as context for generating this wiki page:
The Component Settings Cascade is a multi-tiered resolution logic used in the Nordcom Commerce platform to determine the final configuration of ambient storefront components. It implements a "last-write-wins" inheritance model where settings are resolved from the most specific context (instance-level) down to the most general (platform defaults).
This system allows operators to define global defaults for components—such as Product Cards—while providing the flexibility to carve out exceptions for specific surfaces (e.g., search results) or individual block instances on a page. The cascade ensures that the storefront remains consistent while remaining highly customizable.
Sources: CONTEXT.md:144-156, CONTEXT.md:164-177
Architecture and Tiered Resolution
The Setting Cascade operates across four distinct tiers. Each tier contributes only the keys it explicitly sets; if a key is absent at a higher tier, it inherits the value from the next tier down.
The Four Tiers of Resolution
- Platform Default: The built-in baseline configuration. This includes surface-specific presets defined in the code (e.g.,
SURFACE_PRESETS). - Store-wide Default: A tenant-level configuration that applies across the entire shop. These are stored in the Shop extension manifest within the
basebucket. - Per-surface Override: Configuration specific to a Surface context, such as
collection,search, orrecommendation. - Per-instance Override: The most specific tier, authored on a Block node within a specific page document. This allows a single instance of a component to behave differently than all others in the shop.
Sources: CONTEXT.md:164-177, apps/admin/src/components/customization/components-tab.tsx:30-40
Logic Flow Diagram
The following diagram illustrates how the system resolves a specific setting key by traversing the tiers from highest specificity to the platform baseline.
This flow ensures that specific overrides always take precedence over broader defaults.
Sources: CONTEXT.md:164-177
Data Structures and Configuration
Component settings are governed by the COMPONENT_SETTINGS registry and the Shop Extension Manifest.
Shop Extension Manifest
The manifest serves as the declarative configuration for a shop. It unifies theme tokens, section visibility, and component settings. Component settings are stored under the extensions key in the manifest, organized by component ID and bucket (scope).
| Field Path | Description |
|---|---|
extensions.<id>.base.<name> | The store-wide default for a setting. |
extensions.<id>.<surface>.<name> | A surface-specific override (e.g., search). |
extensions.blockDefaults.<slug>.<name> | Store-wide defaults specifically for Block settings. |
Sources: CONTEXT.md:126-142, apps/admin/src/components/customization/components-tab.tsx:30-35
Component Settings Entry
Each entry in the COMPONENT_SETTINGS registry defines the schema for a component's configurable knobs.
| Property | Type | Description |
| :--- | :--- |
| id | string | Unique identifier for the component. |
| label | string | Human-readable name shown in the Admin UI. |
| surfaces | string[] | (Optional) List of surfaces this component supports (e.g., collection). |
| settings | FieldDescriptor[] | The individual knobs/fields available for configuration. |
Sources: apps/admin/src/components/customization/components-tab.tsx:24-30, CONTEXT.md:158-162
Administration and the Customization Hub
Operators manage component settings within the Customization hub in the Admin app. The "Components" tab provides a unified interface for editing store-wide and surface-specific settings.
Scope Selection
For multi-surface components (like the Product card), the UI provides a "Scope" selector. This allows the operator to switch between the base (all surfaces) and specific surface buckets.
- Inheritance Visualization: The UI utilizes
inheritSourceLabelto show the operator where a value is currently being inherited from if it hasn't been overridden in the current scope. - Inherit/Override Widget: Each field renders a control that allows the operator to explicitly override a value or revert to inheritance (which removes the key from that specific bucket in the manifest).
Sources: apps/admin/src/components/customization/components-tab.tsx:30-65, CONTEXT.md:144-156
Form Integration
The customization hub mounts inside a single editor form. This ensures that all changes—regardless of the tab—are saved and published as a single versioned CMS document.
The diagram shows the interaction between the operator, the form state, and the backend during the editing process.
Sources: apps/admin/src/components/customization/components-tab.tsx:84-95, packages/cms/src/editor/ui/editor-edit-page.tsx:135-155, CONTEXT.md:183-193
Technical Implementation Details
Resolution in Storefront
The resolveExtensions composer is responsible for folding the manifest data into the ResolvedExtensions object consumed by the storefront. It processes the manifest and applies the cascade logic to provide the final values for each component.
Sources: CONTEXT.md:126-142, packages/cms/README.md:120-135
Field Overrides in Blocks
While Component Settings generally refer to ambient UI, Block Settings follow a nearly identical cascade. The primary difference is that Blocks do not use the "Surface" tier but instead allow for per-instance overrides directly on the Block node.
// Example of an overridable block setting in form state
const data = {
sections: [{
title: { 'en-US': 'Support' }, // Localized content
settings: {
layout: 'grid' // Instance-level override
}
}]
};
Sources: CONTEXT.md:108-124, packages/cms/src/editor/ui/editor-fields.test.tsx:90-100
Summary
The Component Settings Cascade provides a structured, predictable way to manage storefront configuration at scale. By separating settings into tiers—Platform, Store-wide, Surface, and Instance—the platform enables granular control without requiring repetitive configuration. This architecture is central to the "multi-tenant" nature of the project, allowing a single deployment to support diverse branding and functional requirements across different shops.
Sources: CONTEXT.md:1-15, CONTEXT.md:164-177