Why saved content differs between Page Builder and the storefront
Compare one heading in saved data, published data, and storefront output to identify the first content stage that needs attention.
In this guide
- Saved configuration
- Published target
- Theme resolution
- Application cache
- Rendered content
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
Use trace-content-version.ts to compare the same heading at three stages: saved editor data, published data, and storefront output. Supply the expected Store, locale, component key, and heading, plus exactly one observation from each stage. The function returns the first stage that differs, or null when all three match.
Collect those observations from the real editor and supported application responses. The function only compares them; it does not read Znode or refresh a cache. Missing or duplicate stage observations raise an error so incomplete evidence cannot look like a healthy result.
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.The fixture expects 'Technical documents version B'. Saved data contains version B, while published data and the storefront contain version A, so firstContentMismatch returns 'published'. Investigate publication before rendering. If published data also contained version B, the first mismatch would move to 'storefront'.
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
Refresh the first stale stage through its supported mechanism. When the issue is authenticated Webstore revalidation, follow the version-specific Znode guide for ZNODE_REVALIDATE_TOKEN in Webstore and the corresponding WebstoreWebhookSecret in API. Deploy the paired configuration and verify its authorization checks.
Then repeat the observation in a fresh public session. Check another Store, the relevant locales, and an older saved page. Record the refresh scope and expected delay so editors and support staff know when a content update should appear. A browser refresh cannot repair missing published data, and republishing cannot fix a renderer that reads the wrong property.
- 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.