Why saved content differs between Page Builder and the storefront
Follow a content change through saved configuration, publication, theme resolution, and application caches before changing the component.
In this guide
The preview is right and the public page is wrong
An editor changes a heading and sees it in Page Builder. The public storefront still shows the previous wording. Rebuilding the component may feel like progress, but the component might never have received the new content. Several independent stages sit between an editor field and a public page.
Use one unmistakable synthetic text change on a non-production page. Record where it appears and where it stops. This turns a vague 'publishing is broken' report into a traceable question about saved data, a published projection, theme selection, or a cached rendering.
Verify what was actually saved
Save the page, leave the editor, and reopen it. If the new value disappears there, the problem is earlier than public publishing. Inspect the declared saved configuration through the supported editor or read path. A local component state update is not evidence of persistence.
Check the component key and property names. An editor can write one property while a renderer reads another. Defaults can also hide a missing value by making the preview look complete. Compare a newly added widget with an older saved instance, especially after changes to required fields or registration names.
Find the first mismatched content stage
trace-content-version.ts compares one saved, published, and storefront observation with an expected Store, locale, component key, and heading. The included fixture demonstrates a publication-stage mismatch. Duplicate or missing observations raise an error rather than silently claiming a healthy stage.
Map observations from the real editor and application responses. Once the stale stage is identified, use that stage's supported refresh mechanism. For releases containing authenticated revalidation, configure ZNODE_REVALIDATE_TOKEN in Webstore and the corresponding WebstoreWebhookSecret in API; the official revalidation guide defines the paired deployment and expected authorization checks.
page-builder/trace-content-version.ts typescript
export type ContentStage = "saved" | "published" | "storefront";
export type ContentObservation = Readonly<{
stage: ContentStage; store: string; locale: string;
componentKey: string; heading: string;
}>;
export type ContentExpectation = Omit<ContentObservation, "stage">;
export function firstContentMismatch(
expected: ContentExpectation, observations: readonly ContentObservation[]
): ContentStage | null {
const order: readonly ContentStage[] = ["saved", "published", "storefront"];
const rowsByStage = order.map(stage => {
const rows = observations.filter(row => row.stage === stage);
if (rows.length !== 1) throw new Error("Supply exactly one observation per stage.");
return rows[0];
});
for (const row of rowsByStage) {
const stage = row.stage;
if (row.store !== expected.store || row.locale !== expected.locale ||
row.componentKey !== expected.componentKey || row.heading !== expected.heading)
return stage;
}
return null;
}
const expected: ContentExpectation = {
store: "SAMPLE", locale: "en-US", componentKey: "ResourcePanel",
heading: "Technical documents version B"
};
const observations: ContentObservation[] = [
{ ...expected, stage: "saved" },
{ ...expected, stage: "published", heading: "Technical documents version A" },
{ ...expected, stage: "storefront", heading: "Technical documents version A" }
];
if (firstContentMismatch(expected, observations) !== "published")
throw new Error("The trace should locate the publication boundary.");
// Map each observation from the actual editor/publication/storefront response.
// Refresh the layer identified by the trace using its supported mechanism.Check theme and application alignment
The editor and storefront must understand the same saved widget contract. A theme override available to Page Builder may not exist in the deployed storefront image. A shared package can still be consumed at different versions by the two applications.
Record application versions or artifact identities during diagnosis. Verify the selected store theme and registration rather than assuming every store uses the same renderer. If the saved value reaches the storefront but does not appear, inspect normalization, translation scope, visibility conditions, and fallback logic. Those are rendering problems, distinct from publication failures.
Invalidate only the layer that is stale
Once the first stale layer is identified, use its supported refresh or revalidation mechanism. A browser hard refresh cannot repair an outdated published projection. Conversely, republishing a catalog is unlikely to fix a component reading the wrong property.
Test the change in a fresh public session after the intended update. Include another store and an older page to detect collateral changes. If a cache refresh is necessary, document its scope, trigger, and expected delay. Avoid adopting a tenant-specific emergency workaround as the normal deployment recipe for every implementation.
- Keep a saved configuration fixture alongside screenshots.
- Verify locale-specific content independently.
- Distinguish an edited draft from a published target.
- Record which layer was observed directly.
Make the next content release easier to diagnose
Add a small release checklist that binds the widget contract, both application artifacts, selected theme, and publication target. Keep the editorial save-and-reopen journey in regression coverage. These checks are more useful than a broad instruction to clear everything whenever content differs.
The public page is the last stage of a content pipeline. Treating each stage as a separate observable boundary helps developers solve the actual mismatch and gives editors a predictable workflow. The result is confidence in publishing, not just another successful refresh during a debugging session.
References and further reading
Independent guidance from GCG. Znode is a trademark of its owner. Examples use fictional data and are not official platform documentation. Suggest a correction.