CMS Environment & Caching Guide
Overview
Our CMS architecture uses Builder.io with three separate "spaces" that map to different environments:
| Space | Purpose | Shopify Store | Webhooks |
|---|---|---|---|
| Production | Live customer-facing content | birdygrace.myshopify.com | Enabled (sends) |
| Staging | Content testing with production-like caching | birdy-grey-test-store.myshopify.com | Receives from Production |
| Homepage | Billing separation for homepage pages | birdygrace.myshopify.com | Receives from Production |
Content Sync Flow
When content is published, unpublished, archived, or deleted in the Production Builder space, a webhook automatically syncs that content to Staging and Homepage spaces.
What Syncs to Homepage Space
Only specific pages sync to the Homepage space:
/(homepage)/suits/hp-promo-banner-test
Shopify Product Translation
When content syncs from Production to Staging, Shopify product references are automatically translated:
- Production GIDs → Staging GIDs (matched by product handle)
- If a product doesn't exist in the staging Shopify store, that product reference is removed from the synced content
Caching by Environment
| Environment | Caching | Content Visibility After Publish |
|---|---|---|
| Production | Enabled | Varies by content type (see below) |
| QA | Disabled | Immediate |
| Staging | Enabled | Varies by content type (see below) |
| Builder Preview | Disabled | Immediate |
Cache TTL by Content Type
| Content Type | Cache Level | Fresh (maxAge) | Stale Revalidate |
|---|---|---|---|
| Recommendation trays | faster | 1 second | 9 seconds |
| Homepage, announcements, header | fast/medium | 1 minute | 4-14 minutes |
| PDP content, PLP navigation | medium | 1 minute | 14 minutes |
| Footer, PDP breadcrumbs, settings | slow | 5 minutes | 55 minutes |
| PLPs, empty cart | slower | 15 minutes | 4 hours |
Liquid Proxy Pages
Full proxy pages (pages served entirely via the Liquid proxy) have different caching. Note that hybrid proxy pages still use Builder content for header and footer.
| Setting | Value |
|---|---|
| Fresh (max-age) | 1 hour |
| Stale Revalidate | 24 hours |
This is an HTTP Cache-Control header that affects browser caching. This means:
- Users may see stale content for up to 1 hour even after updates
- Browser cache persists across sessions until max-age expires
- Hard refresh (Cmd+Shift+R) bypasses browser cache
- Header and announcements on proxy pages will reflect the cached version from when the page was first loaded, not real-time Builder content
When Will Content Updates Appear?
Scenario: Update content in Production Builder
| Environment | Timeline |
|---|---|
| Production | Varies by content type (see Cache TTL by Content Type) |
| QA | Immediate (reads Production space directly, no cache) |
| Staging | Varies by content type (webhook syncs content, then cache expires) |
Scenario: Testing content changes before going live
Step 1: Test in Staging
- Edit content in Staging Builder space
- Use Builder Preview mode to verify changes immediately
- Confirm content looks correct before proceeding
Step 2: Publish to Production
- Recreate the same changes in Production Builder space
- Preview on QA site - changes appear immediately (no caching)
- Verify content on QA before cache expires on Production
- Production site - changes appear after cache expires (timing varies by content type)
- Webhook automatically syncs content to Staging/Homepage spaces
Key Points for Web Ops
- Use QA for testing content changes - no caching means immediate visibility
- Production and Staging have identical caching - timing depends on content type
- Sync is one-way: Production → Staging - edits in Staging Builder don't sync back
- Builder Preview mode bypasses all caching - useful for real-time editing in Builder's visual editor
Static Fallback Content
Every deployment generates static JSON fallbacks for critical content (header, footer, announcements, settings). These are used if the Builder API is unavailable.
Fallbacks are regenerated on each deployment to QA, Staging, and Production.
Environment Comparison
| Aspect | Production | Staging | QA |
|---|---|---|---|
| Builder Space | Production | Staging | Production |
| Shopify Store | birdygrace | birdy-grey-test-store | birdygrace |
| Caching | Enabled | Enabled | Disabled |
| Content Visibility | Varies by content type | Varies by content type | Immediate |
| Receives Webhook Sync | N/A (source) | Yes | N/A (same space) |
| Auto-deploy Trigger | Manual release | Push to main | Version tag |