Add the Contentful SDK or use the Contentful Delivery API REST endpoint directly in your Hydrogen route loaders; pass the Contentful space ID and delivery API token as environment variables
In the product route loader, run the Shopify Storefront API product query and the Contentful query for editorial content in parallel using Promise.all to minimize total latency
Use the product handle or a SKU field stored in a Contentful entry to link the CMS content to the correct Shopify product; establish a linking convention (for example, store the Shopify product handle in a Contentful field named shopifyHandle)
Return both the product and CMS content from the loader and render them in the route component, using the CMS content for sections such as long-form descriptions, video embeds, or editorial photography
Apply appropriate caching strategies: use Hydrogen's CacheLong for CMS content that changes infrequently and CacheShort or no-store for product pricing and availability data
Add a Contentful webhook that triggers a Shopify Oxygen or Vercel revalidation when CMS content is published, so editorial changes appear on the storefront without a manual redeploy
Known gotchas
Running two API calls (Shopify and Contentful) serially in a loader doubles the minimum latency; always run them in parallel and handle the case where one returns null gracefully without blocking the page render
Contentful's Delivery API returns published entries only; preview content requires the Preview API with a separate token and must not be exposed in production builds
CMS-driven content and commerce data can get out of sync if products are deleted in Shopify but the CMS entries are not removed; implement a hygiene check or automation to clean up orphaned CMS entries
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp