Ezi Home Services turns marketing pages into composable content

Why a rich-text CMS didn't fit

The pages aren't free-form prose — they're a sequence of structured components (reviews carousel, services grid, FAQ accordion, before/after slider) that each need live data: current service catalog, real reviews, nearby areas. A "CMS renders markdown to HTML" model doesn't fit a page that's composed UI, not an article.

<ReviewsSection heading="What Ottawa Homeowners Are Saying" />
<AvailableServicesSection title="All Home Services in Ottawa" />
<CityAreasSection heading="Areas We Serve in Ottawa" />
<HowToBookSection title="How Our Home Cleaning Services Work in Ottawa" />

Each tag maps to a component already in the codebase. The binding layer (cmsCityMdxComponents.tsx) injects server-computed context — which city, which live services — that an editor should never have to supply by hand.

Scope

Rolled out in order: pilot on Ottawa's city page, then the remaining 5 cities, then the area template for all 53 neighborhood pages, then the cityService template for all 64 city+service combinations. Nav (buildCityMenu) and breadcrumbs were switched to read the same CMS fields the page renders, closing a gap where they could otherwise silently drift from an editor-changed service catalog.

Decisions that kept it maintainable

Problems hit along the way

Server/client boundary violations. Several section components had no 'use client' of their own — they'd always been rendered from an already-client parent, so they "worked" by inheriting client-ness, not because React does that automatically. Once a server component (MDXContent) rendered them directly, any client-only hook inside threw at render time. Fixed by having each component declare its own boundary.

Functions can't cross the server/client boundary as props. A server-computed closure was being passed into a client component; React allows JSX across that boundary, not functions. Fixed with a small client wrapper that receives only serializable data and builds the closure itself.

Stale in-memory and disk caches masking real publishes. The SDK client caches successful reads for cacheTtlMs (5 minutes) — a manually-published entry 404'd until that cache expired. Separately, a route's 5-day revalidate window had cached a 404 to disk from before an entry existed, which survived a full process restart. Diagnosed by ruling out each layer in turn rather than re-checking the same one.

Templated copy isn't unique copy. Early overrides just substituted the city name into a generic template — technically CMS-controlled, but not yet actually distinct per city. Every section wasn't counted "migrated" until an entry had real, authored copy, not a prop plumbed through to the same fallback every other city would also hit.

"Migrated" and "dead" aren't the same predicate. Once all 6 city pages read from the CMS, the old CityPageView.tsx fallback was unreachable — but WhyChooseUs and FAQSection's default copy were still consumed by the not-yet-migrated area pages. Every symbol's full consumer list was grepped before deleting anything; ~200 lines of exclusively-consumed content came out, everything still load-bearing stayed.

Outcome

All 6 city pages, all 53 neighborhood pages, and all 64 city+service pages are CMS-driven — hero, section copy, FAQ, and structured content blocks all editable without a deploy. Two rendering bugs were caught by the error-boundary design during the pilot rather than shipping broken. Replicating the pattern surfaced a stale FAQ answer referencing services two cities no longer offered, and required real per-city writing for 24 sub-service cards that had no bespoke copy to begin with — a purely mechanical migration would have carried both forward unnoticed.