Performance-governed storefront architecture for Shopify brands that have outgrown the theme model.

A customer should not need to download and execute the architecture of the application in order to use the storefront.

HTML should arrive with meaningful content already rendered. JavaScript should progressively add the interactions that genuinely require it rather than becoming the default delivery mechanism for the entire experience.

Interactive functionality still belongs in the browser. Unnecessary application work does not.

A high-performance storefront should therefore minimize client-side rendering required for initial content, unnecessary hydration, duplicated data, oversized application payloads, and third-party execution on the critical path.

The objective is not to eliminate JavaScript. It is to make every byte of client execution earn its place on the critical path.

A globally distributed runtime is valuable only when the architecture allows requests to benefit from it.

Public catalog experiences are predominantly read-heavy. Product descriptions, merchandising content, collection structures, editorial content, and many other storefront responses do not need to travel through the entire commerce stack on every request.

Where appropriate, responses should be rendered close to the customer, cached close to the customer, reused across requests, invalidated when underlying data changes, and able to remain temporarily available when upstream systems are degraded.

The objective is not simply to deploy the application to an edge platform. It is to remove unnecessary origin work from the customer request path.

Not every part of commerce should be cached. Carts change. Customer information is private. Inventory and pricing can require stronger freshness guarantees. Personalization can change the response for each visitor.

The goal is therefore not maximum caching. The goal is correct caching boundaries.

A high-performance storefront should know, by design, what can be shared globally, what varies by market or locale, what has a short freshness window, what must always be dynamic, what belongs to an individual customer, and what should never enter a shared cache.

Performance comes from aggressively optimizing what is safe to optimize while preserving correctness where commerce requires it.

A storefront is not successful because it scores well in a synthetic benchmark. It must still operate as a complete commerce system.

Shopify should remain responsible for the commerce capabilities it is already designed to own: products, variants, pricing, Markets, cart behavior, customer capabilities, discounts, checkout, payment infrastructure, and the broader merchant ecosystem.

Search, reviews, subscriptions, loyalty, experimentation, analytics, attribution, personalization, localization, accessibility, SEO, and merchant workflows remain part of the engineering problem.

The goal is not to remove complexity until the storefront becomes fast. It is to control complexity so the complete storefront remains fast.

A fast launch is not the same thing as a fast storefront. Production systems accumulate weight.

Analytics vendors are added. Personalization experiments launch. Reviews change providers. Product teams introduce richer interactions. Marketing adds another tag. Dependency updates alter rendering behavior.

Without explicit constraints, performance gradually becomes whatever remains after every other requirement has been implemented.

A high-performance architecture should instead define measurable limits for Core Web Vitals, server and edge response times, client JavaScript, third-party execution, cache effectiveness, error rates, and production regressions.

Performance should not depend on someone periodically remembering to run Lighthouse. It should become a property the system is designed to preserve.

A storefront can be technically fast and still be a poor production architecture.

The system also has to remain understandable, observable, recoverable, and maintainable by the people responsible for it.

A mature headless storefront should make it possible to answer what happens when Shopify is slow, the CMS is unavailable, search fails, invalidation stops arriving, performance regresses, or a deployment introduces an error.

Performance, reliability, and operational simplicity are not separate goals. They are properties of the same system.

The first layer measures outcomes at the browser rather than implementation details inside the application.

For production traffic, Core Web Vitals should be evaluated at the 75th percentile, with mobile treated as the more demanding operating environment.

A single TTFB number is not enough. An edge cache hit and a request that must reach the application, Shopify, a CMS, and other dependencies are fundamentally different execution paths.

Delivery targets should therefore be classified by cache state and route behavior rather than collapsed into one global server-response target.

Performance is not only a question of how quickly the server responds. It is also a question of how much work the browser is asked to perform afterward.

Every important route class should have an explicit initial JavaScript budget covering the code required for meaningful interaction.

The exact budget should be established from the implementation and product requirements rather than declared as an arbitrary universal limit.

A performance target that nobody responds to when it is violated is only documentation.

The system should define both pre-production and production gates so predictable regressions can be caught early while real traffic remains the final validation layer.

For primary storefront routes, meaningful product and content information should arrive in the initial HTML whenever practical.

The browser should not need to download the application, execute the framework, discover required APIs, fetch commerce data, and construct the page before the customer can see what they requested.

Resolving critical data before the response reaches the browser can remove client-side waterfalls, reduce dependence on device capability, and make the initial experience less dependent on successful JavaScript execution.

The browser should receive the result of application work whenever it does not need to perform that work itself.

A headless storefront may depend on Shopify, a CMS, search, reviews, personalization, recommendations, inventory systems, and proprietary services.

That does not mean the customer's browser should coordinate those systems.

The storefront application should normally act as the composition layer, giving the architecture control over authentication, secrets, request parallelism, timeout behavior, caching, normalization, observability, fallbacks, and the amount of data ultimately exposed to the client.

Headless should separate presentation from commerce without turning the browser into the integration layer.

Moving API calls away from the browser does not make inefficient orchestration free.

Independent dependencies should execute concurrently where safe. Sequential work should exist because one result genuinely depends on another, not because the implementation happened to request each service one after the other.

Moving a waterfall away from the browser does not remove its latency. The application still has to schedule data work deliberately.

Not every dependency on a page deserves equal priority.

A product detail page may need core product information, current commerce state, and the primary purchase controls immediately while recommendations, long-form reviews, and personalization can tolerate arriving later.

Streaming becomes useful when different parts of the page have genuinely different dependency costs.

If the primary product experience can be produced quickly while recommendations or another secondary integration takes longer, the slower dependency should not necessarily prevent useful HTML from beginning to reach the browser.

Streaming does not make slow dependencies fast. It prevents appropriately isolated slow dependencies from blocking unrelated work.

Server rendering alone does not guarantee a small client payload.

An application can retrieve large Shopify responses, complete CMS documents, internal normalized models, and recommendation metadata on the server and then serialize all of it into the document for hydration.

The architecture should distinguish data required to render the page from data required to continue interacting with it. Those sets are often very different.

Server-rendered data should not automatically become client state.

A custom storefront can combine information from many systems without becoming the source of truth for those systems.

Shopify should continue to own commerce state that belongs to Shopify. The CMS should own editorial content. Search should own its index. The storefront should own presentation composition and delivery policy.

Composition belongs to the storefront. Commerce truth should remain with the system that owns it.

Every synchronous integration added to rendering becomes capable of delaying or failing the customer request.

CMS, search, reviews, personalization, recommendations, and other services should therefore become request-path critical only when the initial customer experience genuinely requires them.

A service should become request-path critical because the customer experience requires it, not because integration was easiest that way.

Many storefront experiences are dominated by public, read-heavy traffic: product descriptions, media, collection structure, navigation, merchandising content, editorial content, and SEO metadata.

When the same representation is valid for many customers, the architecture should be able to serve it without reconstructing it from upstream systems on every request.

Public traffic should reuse completed work whenever the underlying commerce semantics allow it.

A response can be public without being globally identical. Market, locale, currency, catalog context, pricing rules, and merchandising can all change what a valid response looks like.

The real question is therefore not simply whether a route can be cached.

The architecture must define what makes two responses equivalent.

Different commerce data deserves different freshness guarantees.

A product description arriving slightly after a source update may be acceptable. Pricing, inventory, customer state, or transactional information can have very different business consequences.

The architecture should therefore classify data by semantics rather than assigning one TTL to an entire route.

These are policy categories, not universal cache durations. Actual freshness windows belong to the merchant's operational requirements.

Long-lived cache entries do not necessarily imply slow content updates.

Shopify and CMS events can notify the storefront when relevant source data changes, allowing entries to remain reusable under normal conditions while still being invalidated when the underlying state changes.

A long TTL and fresh content are not necessarily opposites when invalidation is reliable.

Event-driven invalidation should not become the only mechanism preventing stale data.

Webhooks can be delayed, duplicated, delivered out of order, or missed entirely. A cache entry should therefore not remain incorrect forever merely because an invalidation event failed.

Event-driven invalidation can be combined with bounded expiration and revalidation so the normal path reacts quickly while the failure path still has a freshness ceiling.

Invalidation provides speed. Expiration provides safety.

When temporary staleness is acceptable, a slightly expired response does not always need to make the customer wait for an upstream refresh.

The existing representation can be returned immediately while the architecture refreshes the entry independently for future requests.

Stale-while-revalidate is useful only where temporary staleness is an acceptable commerce outcome.

A product detail page may combine durable product content, freshness-sensitive pricing and availability, and private customer or cart state.

Treating the entire page as one freshness unit creates two bad extremes: caching everything and risking correctness, or caching nothing and unnecessarily rebuilding durable content.

The freshness requirement of the most dynamic field should not automatically determine the caching policy for the entire page.

Cart state, authenticated customer information, entitlements, account data, and other private commerce state should not enter a cache that can be reused across customers.

Those routes may still benefit from server execution, optimized upstream calls, connection reuse, or request-scoped/private caching where appropriate, but their performance model is fundamentally different from public catalog traffic.

Private commerce data should remain private even when that means giving up shared-cache efficiency.

A custom presentation layer does not need to recreate transaction and payment infrastructure simply because the rest of the storefront is headless.

The storefront should prepare cart state correctly and hand the transaction to Shopify's checkout boundary.

Transactional complexity should remain with the platform designed to own it.

Public cached representations can provide more than lower latency. They can also reduce how directly an upstream slowdown propagates to customers.

But stale serving is not appropriate for every data class. The architecture needs an explicit failure policy based on what the customer is allowed to see when a dependency is unavailable.

A route described as edge-cached is not necessarily behaving like an edge-cached route in production.

Cache fragmentation, accidental bypasses, incorrect headers, excessive invalidation, or an unexpected request variant can silently move traffic back toward the origin.

Caching should be treated as production behavior to verify, not configuration to assume.

Every integration should have an owner and a reason to exist.

Installing a vendor should begin with the business capability being purchased rather than the mechanics of adding another script or tag.

A third party should enter the critical path because the business deliberately accepted its cost, not because installation was easy.

Not every integration should execute for every customer immediately.

Consent state can determine whether processing may begin, which events may be collected, which identifiers may be used, and whether data may be forwarded to analytics or advertising destinations.

Consent should therefore participate in the execution model, rather than acting only as a banner layered over an otherwise unchanged script architecture.

Consent should control execution, not merely record a preference after execution has already happened.

A storefront should not require every analytics and marketing vendor to independently infer customer behavior from DOM selectors, duplicated event listeners, and its own version of commerce state.

The storefront can instead define a canonical event model for meaningful commerce actions and allow integrations to consume those events through adapters.

The storefront should define what happened. Analytics vendors should not independently decide what happened by scraping the page.

Some integrations genuinely require browser execution: interaction measurement, consent UI, presentation-changing experiments, client personalization, session replay, support widgets, and other browser-dependent functionality.

Other destination delivery may not require every vendor to independently execute inside the customer device.

A first-party event endpoint or server-side pipeline can forward suitable events to supported destinations while preserving a smaller browser execution surface.

Server-side forwarding can reduce duplicated browser work, but it does not make browser requirements, consent obligations, attribution semantics, or vendor limitations disappear.

A fast storefront with unreliable revenue attribution is not a successful storefront.

Product views, search, collection interactions, add-to-cart, cart changes, checkout initiation, purchases, attribution, consent state, experiments, market context, and currency still need trustworthy measurement where the business requires it.

Performance optimization should reduce unnecessary measurement cost, not measurement integrity.

Transfer size alone is not enough to describe the cost of an integration.

A relatively small script can still create expensive parsing, compilation, main-thread work, long tasks, network contention, or layout changes.

The performance contract should therefore govern third-party execution across multiple dimensions.

Integrations should be scheduled according to how directly they contribute to the customer task.

Some functionality may be required immediately. Other systems can wait until useful content is available, until consent has been granted, or until the customer invokes the feature.

Loading priority should follow customer value rather than the order in which vendors were added to the storefront.

A tool required on a product detail page does not necessarily belong on every editorial route.

Search analytics can be scoped to discovery experiences. Reviews can load where review interaction exists. Experiments can execute only where their variants apply. Support widgets can remain on-demand.

Third-party scope should follow the routes and interactions that genuinely require the capability.

Once the storefront owns its event model, analytics becomes application infrastructure rather than an accumulation of vendor-specific DOM triggers.

Events such as product viewed, product added, cart viewed, checkout started, and purchase completed should have known schemas and predictable semantics.

That makes event existence, required fields, duplicate delivery, sequencing, consent enforcement, destination forwarding, and revenue values testable.

Analytics should behave like a tested interface, not an accumulation of DOM selectors and tag-manager triggers.

Analytics, advertising, session replay, reviews, and other non-critical integrations should generally fail independently from core commerce.

Add-to-cart should not wait for an advertising endpoint. Checkout navigation should not depend on session replay. A failing review provider should not make the primary product experience unusable.

A non-critical third party should never become a hidden synchronous dependency of a critical customer action.

Analytics can remain technically operational while producing incorrect business data.

Releases can duplicate purchase events, remove required fields, reduce event volume, break forwarding, or alter attribution without generating an obvious storefront error.

Measurement health should therefore be monitored as a production system in its own right.

Shopify remains the authority for the core commerce model: products, variants, catalogs, markets, pricing, carts, discounts, customer commerce state, checkout, orders, and payments.

The exact API involved can vary by capability, but the ownership boundary should remain clear.

The storefront may normalize, transform, or combine Shopify data into a presentation model without creating another competing source of truth for the same commerce state.

The storefront may reshape commerce data for delivery without taking ownership of commerce truth.

The storefront sits between the customer and the systems required to produce the experience, but it is more than a transparent proxy.

It decides which systems need to be contacted, which requests can execute concurrently, which results can be reused, which failures can degrade, which data belongs in the initial response, which work can be deferred, and what ultimately reaches the browser.

This is also where the policies established in Chapter 02 become operational: performance budgets, rendering strategy, cache boundaries, client execution, and third-party governance.

The storefront is both the presentation layer and the policy-enforcement layer for customer delivery.

Mature storefronts often require content, search, reviews, experimentation, personalization, analytics, loyalty, subscriptions, and other capabilities beyond Shopify's core commerce responsibilities.

Those systems can remain authoritative for the specialized capability they provide rather than being collapsed into another storefront-owned database.

Composable does not mean every system becomes equally important to every request.

The existence of an integration does not automatically justify placing it between a customer request and a useful storefront response.

A product detail page may require Shopify product data, market context, and required content before it can be correct. Reviews, recommendations, analytics forwarding, personalization, and secondary content may not need to block that response.

A dependency becomes critical because the experience cannot be correct without it, not because the integration exists.

Critical work is required before the customer can receive a correct and useful primary experience.

Asynchronous work can proceed after that response, independently of it, or only when the customer invokes the relevant capability.

Making this distinction explicit prevents optional capabilities from silently accumulating on the critical request path.

The edge can perform cache lookup, routing, response reuse, request normalization, stale serving where permitted, and selected lightweight execution close to the customer.

Those capabilities reduce repeated work and geographic delivery cost without changing which system owns the underlying commerce state.

The edge accelerates delivery. It does not become the source of truth for commerce.

The internal storefront architecture can depend on many systems without requiring the customer's device to independently orchestrate those systems.

The browser should primarily receive rendered HTML, CSS, the data required for continued interaction, and the JavaScript needed for genuinely interactive regions.

Server-side composition also keeps credentials private, allows upstream APIs to be normalized, limits serialized data, and avoids exposing avoidable request waterfalls to the customer network.

The internal system graph can be complex without exposing that complexity directly to the customer device.

Shopify can remain authoritative for commerce while the storefront derives the presentation model required for a route. The CMS can remain authoritative for content while the storefront decides how that content is placed into the experience.

Each boundary should deliberately reduce data to what the next layer actually needs instead of forwarding complete upstream representations through every layer.

Each boundary should pass the minimum data required by the next layer, not simply forward the full upstream representation.

Public catalog traffic can use shared delivery and cache paths where response semantics allow reuse.

Cart and authenticated customer state cross a different boundary. Those requests remain customer-specific and should not inherit shared-cache behavior simply because they originate in the same storefront.

Shared delivery optimizations stop where customer-specific commerce state begins.

A custom presentation layer does not require rebuilding payment, checkout, and transaction infrastructure.

The storefront prepares the correct commerce state and hands the transaction to Shopify's checkout boundary.

The storefront owns the path to checkout. Shopify owns the checkout transaction.

Dependency topology should not decide how widely a failure propagates.

Required commerce data may need a controlled error or safe stale fallback. Optional recommendations can disappear. Personalization can fall back to a default experience. Analytics failure should not stop a commerce action.

The architecture should fail according to business importance rather than dependency topology.

A slow request is not actionable until the system can explain where its time was spent.

Edge delivery, storefront rendering, Shopify requests, supporting APIs, browser experience, and analytics delivery should each expose enough information to distinguish one class of failure or latency from another.

Observability should answer where the time was spent, not merely report that the page was slow.

Core catalog behavior remains anchored to Shopify: products, variants, options, collections, availability, pricing, metafields, merchandising data, and product identity.

The storefront can change how that information is presented, composed, cached, or interacted with without creating a parallel product model that gradually diverges from Shopify.

Commerce truth stays in Shopify. Presentation freedom belongs to the storefront.

International storefront behavior is more than displaying a currency selector.

Country, language, currency, pricing, availability, catalog, routing, cart buyer context, and checkout context can all participate in determining the correct experience.

A storefront that renders one market on the product page and silently loses that context in cart or checkout has not achieved functional parity.

Localization is presentation. Market context is commerce state. The architecture has to preserve both.

The custom storefront owns the cart experience while Shopify continues to own the underlying commerce state and transaction boundary.

Variant identity, quantities, market context, discounts, buyer state, gift cards where applicable, and checkout transition should remain coherent across that boundary.

The storefront can redesign the shopping journey without redefining the transaction.

A mature customer experience can include authentication, profile data, addresses, orders, fulfillment information, refunds, session lifecycle, and checkout identity.

The presentation can be custom while Shopify remains the authority for customer commerce state.

Creating a second customer identity system without a clear requirement introduces synchronization and security responsibilities that the storefront does not need to own.

Custom account experience does not require custom customer identity.

A product is not always a simple variant and quantity. Subscription plans, bundles, multipacks, pre-orders, gift products, and other purchasing models can introduce additional commerce semantics.

Shopify or an external commerce provider may own those semantics, but the custom storefront still has to implement the selection, presentation, validation, and cart behavior required by the customer.

API support establishes capability. Storefront parity still requires implementing the customer experience around that capability.

Search, reviews, loyalty, subscriptions, personalization, wishlists, support, back-in-stock tooling, affiliate systems, experimentation, and other integrations do not disappear when the storefront becomes headless.

Some capabilities map naturally to Shopify APIs. Some vendors provide APIs or dedicated headless integrations. Others depend heavily on Liquid, theme blocks, DOM injection, or Online Store runtime behavior.

Those dependencies have to be discovered and classified before the migration architecture is finalized.

App compatibility is discovered during migration assessment, not assumed after development begins.

Shopify can remain the product system of record while a specialized search platform owns indexing, ranking, facets, query behavior, and merchandising.

The important boundary is that the discovery representation remains derived from authoritative commerce data rather than becoming a competing product database.

The search system can own discovery relevance without becoming the authority for commerce truth.

A migration can improve Core Web Vitals while still failing the business if purchases, attribution, consent, experiments, or ecommerce events become unreliable.

Parity should therefore be evaluated at the business outcome level rather than by checking whether the legacy scripts were copied into the new storefront.

Analytics parity means preserving trusted business measurement, not reproducing the exact legacy script topology.

The commerce platform still supplies much of the underlying catalog information, but the presentation layer becomes responsible for exposing that information correctly to crawlers and social systems.

Headless does not automatically improve SEO. It provides greater implementation control and therefore greater responsibility to implement the requirements correctly.

Headless does not remove Shopify SEO capability. It moves more responsibility for expressing it correctly into the storefront.

Customer-facing functionality is only one side of a commerce platform.

Merchandising, content, campaigns, redirects, Markets, discounts, customer support, app workflows, and routine operational changes should continue to be manageable without turning ordinary commerce work into engineering work.

Preserve Shopify as an operational commerce platform, not merely as a backend database.

The migration should begin with a capability inventory derived from the actual incumbent storefront rather than a generic Shopify checklist.

Every meaningful capability receives an explicit migration decision, implementation path, owner, and acceptance gate before traffic moves.

Parity does not require reproducing every technical or visual detail of the incumbent implementation. It requires preserving the business capability and outcome that implementation exists to provide.

Nothing disappears accidentally.

The storefront needs routing, data loading, server rendering, streaming, server-only execution, client navigation, endpoints, middleware, and explicit boundaries between server and browser work.

TanStack Start gives the application a unified place to express those capabilities without requiring separate rendering, frontend, and backend applications merely to control where work happens.

That does not make every route server-rendered in exactly the same way. The correct strategy still follows the route's data, privacy, interaction, and freshness requirements.

The framework provides the execution primitives. The storefront architecture decides how they are used.

A commerce route carries more architectural meaning than its pathname.

Parameters, market context, required data, loading behavior, rendering strategy, error behavior, and client navigation all participate in defining the experience.

Keeping those concerns inside an explicit route and data model makes it easier to reason about what work each experience requires before it reaches the customer.

A storefront route should describe an experience boundary, not merely point to a component.

Shopify requests, CMS composition, search orchestration, customer-session handling, event forwarding, webhook processing, cache invalidation, and private configuration should not automatically become browser concerns.

Server-side application boundaries provide a natural place to enforce validation, authentication, normalization, timeouts, observability, and data minimization before a result reaches the customer device.

Backend capability remains available to the storefront without turning the browser into the backend client.

The application framework determines how storefront work is expressed. The delivery platform determines where requests execute, where static assets are served, and where reusable responses can avoid repeating application work.

The useful distinction is not simply that application code can execute close to the customer.

The delivery layer can distinguish requests that genuinely need application execution from responses that can safely be reused.

The delivery platform is valuable because it can enforce the caching and execution policies established earlier, not because deployment to an edge runtime automatically makes the storefront fast.

The application primarily benefits from a runtime model based on familiar web primitives such as Request, Response, headers, fetch, streams, and Web Crypto.

That keeps application boundaries relatively portable while still allowing the broader JavaScript and npm ecosystem to participate where runtime compatibility exists.

Compatibility should still be verified dependency by dependency. A compatibility layer is not the same thing as every Node behavior being identical in every runtime.

Runtime compatibility is something the production build proves, not something the architecture assumes.

This architecture is not attempting to make the merchant independent from Shopify.

Shopify is intentionally retained for catalog, pricing, Markets, carts, customer commerce state, checkout, and the wider commerce platform the business already relies on.

The goal is instead to avoid unnecessarily coupling unrelated presentation and delivery concerns to a single storefront framework or hosting product.

The implementation does not reject Shopify's storefront ecosystem. It keeps the application architecture free to use the Shopify capabilities and primitives that fit it.

The performance model already has the primitives it needs: server rendering, server data loading, streaming, server-only execution, deliberate client boundaries, code splitting, controlled serialization, and explicit cache policy.

Experimental rendering features may later prove useful for a specific workload, but they should be evaluated against the same performance contract as every other architectural change.

Experimental technology may improve an implementation. It should not be required to justify the architecture.

TanStack Start offers an application model that closely matches the boundaries this storefront needs, but adopting a younger full-stack framework also introduces maturity risk.

The relevant decision is whether the control gained is worth the upgrade diligence, ecosystem uncertainty, and smaller production history compared with older alternatives.

Choosing the framework means accepting its maturity risk, not pretending that risk does not exist.

Commerce semantics, content adapters, search behavior, measurement events, and caching policy should not become inseparable from framework-specific APIs.

The framework should coordinate application services rather than becoming the place where every business integration is directly implemented.

A future framework migration would still be meaningful work, but changing the rendering framework should not require redefining products, analytics semantics, search ownership, or commerce rules at the same time.

Portability does not mean switching frameworks is free. It means the cost is contained instead of distributed through the entire commerce model.

Workers, cache APIs, deployment behavior, observability, queues, storage primitives, or other infrastructure can create legitimate platform-specific implementation.

The goal is not to avoid those capabilities. It is to keep the business policy they implement separate from low-level platform calls.

Product components should express the required cache or background-processing behavior through application boundaries rather than carrying infrastructure-specific implementation everywhere.

Platform-specific capability is allowed. Platform-specific policy should remain localized.

No individual technology in the implementation is the performance architecture.

The stack is useful because, together, its layers give the storefront explicit control over routes, server execution, browser execution, commerce integration, delivery, caching, measurement, and specialized systems.

Technology is selected for the architectural control it provides, not because its name is part of the product.

Similar performance principles can be implemented with other full-stack React frameworks, Shopify-oriented frameworks, server runtimes, and delivery platforms.

The meaningful comparison is therefore not which logo is inherently fastest. It is which implementation model best expresses the organization's required rendering, data, caching, commerce, operational, and deployment boundaries.

The full comparison belongs later in the architecture alternatives decision record.

This implementation is a fit decision, not a claim of universal technical superiority.

The current reference implementation focuses on a production-style landing experience rather than attempting to reproduce an entire merchant catalog.

The measured route contains CMS-driven editorial content, a deliberately media-heavy hero, product merchandising, variant selection, analytics, and representative third-party execution. The reference implementation also includes quick add, search, and a functioning cart, but those interactions are not represented as scripted performance evidence in the current snapshot.

Collection-listing and product-detail routes, scripted interaction performance, and production field traffic remain outside the current evidence boundary.

Lighthouse was collected across repeated mobile and desktop runs against the same implementation build.

Trace-observed LCP and Lighthouse's simulated LCP are reported separately because they diverge materially, particularly under the mobile profile.

The synthetic distribution is evidence about the reference route, not field Core Web Vitals for a production merchant.

Cache HIT, cache MISS, and intentional diagnostic bypass were verified independently rather than collapsed into one latency result.

The same evidence set also attributes diagnostic server work to the application, CMS, and Shopify boundaries.

Reuse and execution are different architectural states, so their latency should remain different measurements.

Browser observation continues after the load event so deliberately deferred analytics, support, and other representative execution remain visible.

This settled profile makes deferred work visible rather than treating the initial navigation as the entire customer-device cost.

Server delivery and customer-device execution remain separate dimensions of the performance architecture.

Third-party functionality remained enabled during the settled browser observation rather than being removed to improve the result.

The observation window intentionally captures deferred execution that may not appear in an initial-navigation benchmark.

Third-party cost is allowed to appear in the evidence instead of disappearing from the benchmark environment.

Route, build, sample size, cache state, observation window, environment, and measurement date remain part of the evidence.

A number without its measurement conditions is weaker evidence than it first appears.

The system exists, important runtime behavior has been measured, and the results are tied to a known implementation build and repeated.

Controlled merchant parity, production field evidence, and commercial validation remain later gates because they answer questions the reference implementation cannot answer by itself.

Before the replacement is judged, the incumbent storefront needs a production baseline across representative routes and customer segments.

That baseline should include field experience, delivery behavior, browser execution, commerce latency, errors, and the business measurement required to interpret the migration.

The reference implementation does not substitute for the merchant's starting condition.

Comparable routes, content, commerce, integrations, device, network, cache state, and measurement method are prerequisites for a strong head-to-head claim.

The current reference release has not established a controlled incumbent comparison.

Catalog, market context, pricing, cart, checkout, customer flows, analytics, consent, search, reviews, SEO, and merchant workflows should follow the parity decisions established in Chapter 03.

Performance is measured on the storefront the business would actually ship, not on a stripped-down technical demonstration.

An absolute budget determines whether an experience remains inside the agreed operating envelope.

A release baseline determines whether a change materially improved or degraded the experience even when the final value still passes the absolute budget.

PageSpeed Insights remains an independent external lab snapshot rather than being merged into the repeated local Lighthouse distribution.

Public CrUX and first-party production RUM remain separate evidence layers because they answer different questions from controlled lab measurement.

Production validation should compare Shopify transaction truth with the analytics signals used for attribution and business decisions.

Revenue measurement remains part of the release gate, not post-launch cleanup.

Technical evidence can establish that a storefront became faster. It cannot by itself establish why conversion, engagement, or revenue changed.

Performance earns technical confidence. Business experiments determine commercial impact.

Migration begins by discovering what the current production storefront actually does, not by beginning with the capabilities of the new framework.

Commerce, integrations, presentation behavior, SEO, analytics, and merchant operations all form part of the incumbent system.

Not every implementation detail needs to survive, but every required business capability receives an explicit migration decision.

The incumbent is not merely legacy code. It is the current specification of the business in production.

Performance, reliability, analytics, commerce behavior, and SEO should be measured before the candidate becomes the comparison point.

This establishes what the replacement needs to improve and prevents the project from retrospectively redefining what success meant before the migration began.

The migration inherits the incumbent baseline before it inherits incumbent traffic.

The candidate is built beside the incumbent rather than mutating the incumbent into the replacement.

Both presentation layers can operate against the same Shopify commerce authority while the new implementation is developed, integrated, measured, and tested.

The candidate storefront should earn production traffic before it replaces production infrastructure.

Products, pricing, markets, carts, customers, checkout, orders, and payments remain Shopify responsibilities throughout the presentation migration.

That reduces the number of major system boundaries changing at once and makes the comparison between storefronts easier to interpret.

Migration risk is reduced when the system of commerce does not move at the same time as the system of presentation.

The merchant should continue using the authoritative Shopify and supporting-system workflows wherever possible while the presentation layers coexist.

Product changes, pricing, inventory, discounts, markets, orders, and customer support should not require separate incumbent and candidate administration.

Parallel storefronts should not create parallel commerce operations.

Migration requires a control plane capable of deciding which storefront receives a request without treating DNS cutover as the experiment itself.

Routing can use internal access, explicit cohorts, percentages, markets, routes, or other merchant-appropriate policies while keeping the allocation observable and reversible.

Traffic allocation should be a runtime decision, not a one-time infrastructure switch.

Production-connected internal traffic can exercise real Shopify data, market configuration, analytics, authentication, checkout handoff, CDN behavior, deployments, and operational tooling without immediately transferring customer responsibility.

This creates an intermediate confidence state between test environments and public rollout.

Production connectivity can be proven before production customer responsibility is transferred.

Production request patterns can sometimes help exercise the candidate before real users are routed to it, particularly for safe read-oriented traffic.

Customer mutations are different. Cart writes, account changes, checkout actions, payments, and orders should not be casually replayed simply to generate realistic load.

Shadowing can reproduce observation safely. It must not duplicate transactional intent.

Percentage routing should normally establish stable cohorts rather than randomly selecting a storefront for each request.

Stable assignment keeps the customer journey coherent and makes performance, analytics, conversion, errors, and commerce behavior interpretable by storefront variant.

A customer should experience a storefront, not a coin flip on every navigation.

Production exposure should grow through evidence gates rather than automatically advancing because a project calendar reached the next date.

The exact percentages are merchant-specific. What matters is that each traffic state creates an observation window followed by a decision to advance, hold, or roll back.

Traffic allocation follows evidence. The calendar does not automatically advance the rollout.

Some experiences may be able to move independently, but crossing between incumbent and candidate introduces session, cart, market, analytics, navigation, and SEO boundaries that have to remain coherent.

When those boundaries introduce more risk than they remove, storefront-level cohort routing may be the cleaner migration strategy.

Route-by-route migration is a tool, not an automatic strategy.

A customer may arrive on the candidate with commerce state that originated on the incumbent, or return to the incumbent after a rollback.

Cart identity, stale identifiers, buyer context, and compatibility between the two presentation layers therefore require explicit migration behavior.

Traffic can move independently. Customer commerce state cannot be treated as disposable.

Both storefronts can continue handing the customer into Shopify Checkout, avoiding the need to operate two independent payment and order transaction systems during the migration.

The candidate still has to prove correct cart state, market, discounts, buyer identity, checkout transition, and attribution.

The presentation can be experimental while the transaction boundary remains intentionally boring.

When incumbent and candidate are serving production simultaneously, analytics needs enough context to determine which experience produced each relevant event.

The canonical event model should remain shared rather than creating two incompatible analytics implementations simply because two storefronts exist temporarily.

A migration experiment that cannot distinguish control from treatment cannot produce trustworthy evidence.

A presentation migration should avoid introducing an unrelated URL migration unless the business has an independent reason to change its information architecture.

Canonicals, redirects, status behavior, structured data, sitemaps, robots rules, localization signals, and internal links should be validated as part of parity.

Changing the renderer does not require changing the address of the resource.

While the incumbent remains available, a failed candidate release can become a traffic-allocation problem rather than an emergency rebuild-and-redeploy problem.

Production exposure can return to the incumbent while the candidate is investigated away from the customer path.

The fastest rollback is the one that does not require fixing the new storefront first.

Returning traffic to the incumbent is insufficient if customers lose carts, authentication, market context, checkout continuity, or interpretable analytics.

Rollback should therefore be exercised as a customer-journey test, not merely as proof that the incumbent homepage still responds.

Rollback succeeds when the customer journey remains recoverable, not merely when the old application responds.

Maintaining two storefronts forever creates its own maintenance, security, dependency, operational, and developer burden.

The incumbent therefore needs explicit retirement criteria rather than remaining indefinitely because it once served as the rollback path.

Reversibility is valuable during uncertainty. Once uncertainty is sufficiently reduced, unnecessary parallel infrastructure becomes risk of its own.

The team should be able to see the candidate release, active traffic allocation, cohorts, route coverage, performance, commerce health, analytics health, rollback readiness, and current gate state without reconstructing them from deployment history.

A migration state should be observable as a system condition, not reconstructed from deployment history.

A dependency becomes critical because the current customer task cannot remain correct or meaningful without it, not because the integration happens to exist.

The same provider can therefore occupy different levels of criticality on different routes. Search may be essential on a search results route and irrelevant to cart.

Dependency criticality belongs to the customer task, not to the vendor.

An integration contract should describe more than its endpoint, credentials, and response schema.

It also needs a timeout, retry policy, stale policy, fallback, expected customer impact, observability signal, and recovery path.

Failure behavior is part of the integration contract.

A dependency can remain technically available while still producing an outage through excessive latency.

Critical-path dependencies therefore need explicit time budgets. Once the allotted budget is exhausted, the appropriate failure policy should run instead of allowing the customer request to wait indefinitely.

A timeout is not merely an HTTP setting. It is an architectural decision about how much customer time a dependency is allowed to own.

Retrying a transient read can improve resilience. Retrying every failed operation can amplify an outage, consume the remaining latency budget, or duplicate a mutation.

Retry behavior therefore considers idempotency, remaining request budget, upstream pressure, and the possibility of executing the action twice.

Retry only when another attempt is safer than accepting the failure.

Public data does not have one universal freshness requirement. Editorial content, product descriptions, price, inventory, cart, and customer state tolerate failure differently.

When the freshness policy explicitly permits it, a known cached response can preserve useful customer experience during upstream failure.

Stale is not the opposite of correct. For some data, bounded staleness is the correct failure behavior.

Event-driven invalidation can make content fresh quickly, but webhook delivery itself is another dependency that can fail.

Bounded TTL and revalidation provide a second line of defense so a missed invalidation event cannot make stale data permanent.

Invalidation provides speed. Expiration provides safety.

Reviews, recommendations, personalization, loyalty, support, and other enhancements should not become accidental requirements for rendering unrelated commerce.

The application needs data and presentation boundaries that let those capabilities degrade or disappear without collapsing the customer's primary task.

Optional capability should fail as optional capability.

Personalization, experimentation, recommendations, and promotional enhancements should have a baseline experience that remains valid when the enhancement layer is unavailable.

That baseline creates an operationally useful state between enhanced and unavailable.

An enhanced experience should normally degrade toward a valid default experience, not toward no experience.

Search has route-specific importance. Failure on a search route may require an explicit degraded state, while the same provider can disappear from predictive search without affecting product or cart behavior.

Search failure should reduce discovery capability, not erase unrelated commerce capability.

Shopify owns commerce truth. Safe cached public data may allow the storefront to preserve some presentation during an upstream failure, but transactional actions cannot be fabricated.

If an add-to-cart, discount, authentication, cart update, or checkout operation cannot be confirmed by the commerce authority, the storefront should not tell the customer that it succeeded.

Degrade presentation when safe. Never invent commerce success.

A failed checkout transition should preserve the cart, surface a controlled error, and allow a later retry rather than losing customer state or presenting a transaction that did not occur.

Transaction failure should be visible, recoverable, and truthful.

Measurement integrity matters to the business, but an analytics destination should not sit in the synchronous success path of a commerce mutation.

Required commerce work and measurement delivery need distinct runtime boundaries so analytics failure can degrade measurement without changing whether the cart action itself succeeds.

Analytics must be reliable enough to trust without being powerful enough to block commerce.

External browser code can throw errors, create long tasks, inject unstable layout, produce request storms, or conflict with other scripts.

Route scope, consent boundaries, deferred loading, defensive adapters, feature flags, and kill switches provide operational ways to limit that blast radius.

A problematic third party should be disableable without requiring a storefront rewrite.

Non-core capabilities should be disableable quickly when they are implicated in an incident or uncertain rollout.

Flags themselves need ownership, a default state, observability, and a review or expiry condition so temporary operational controls do not become permanent architectural ambiguity.

A feature flag is valuable when it creates a safe operating boundary, not when it becomes permanent architectural ambiguity.

A dependency that repeatedly fails can consume application capacity and customer latency on every request.

Where the integration justifies it, a circuit breaker can temporarily stop attempts, use the documented fallback, probe for recovery, and restore the dependency when it becomes healthy.

When repeated failure is known, resilience may mean temporarily stopping the attempt.

Cache failure can increase latency and origin traffic by forcing the application to execute more often.

It must not cause private, cross-market, stale-beyond-policy, or otherwise incorrect responses to be served merely to preserve a cache hit.

A cache is an optimization layer. Correctness must survive its absence.

Once the incumbent is retired, deployment failure still needs a known-good recovery path.

During migration the rollback target may be the incumbent. After migration it becomes the previous known-good candidate release or another deliberately maintained recovery state.

Reversibility survives the migration, even when the rollback target changes.

A healthy build can still break production through a missing credential, incorrect market configuration, broken cache key, wrong origin, analytics destination, or feature flag.

Important configuration therefore receives validation, environment discipline, observability, and pre-traffic testing.

Configuration participates in the production system and deserves the same release discipline as code.

A fallback that remains active for days without anybody noticing is hidden degradation, not healthy resilience.

The team should be able to observe which dependency failed, how often fallback activated, which routes were affected, how long degradation lasted, and whether the dependency has recovered.

Graceful degradation must be visible internally even when it is invisible to the customer.

The final test of resilience is proportionality.

A review outage should remove reviews, not the PDP. Analytics failure should affect measurement, not cart latency. Personalization failure should produce the default experience, not an empty page. Search failure should reduce discovery rather than interrupt checkout.

The customer impact of a failure should be no larger than the capability that actually failed.

The evidence process does not disappear when candidate traffic reaches one hundred percent.

Production RUM, application telemetry, cache state, commerce health, browser execution, and measurement integrity become the permanent operational evidence used to judge future releases.

The production system that proved the architecture becomes the system that protects it.

A storefront-wide average can hide a poorly performing product page, cart, search experience, market, device class, or release.

Operational monitoring should retain enough segmentation to expose meaningful route and journey differences while avoiding cohorts too small to interpret.

Performance governance operates where customers experience the system: at meaningful route and journey boundaries.

Performance budgets should remain connected to the release process rather than becoming launch documentation that is never evaluated again.

Some checks can be automated. Others may require engineering review or an explicit commercial exception.

A performance budget is useful only if exceeding it creates a decision.

Absolute thresholds determine whether current behavior is acceptable. Release-to-release comparison determines whether the system materially changed.

A route can remain inside budget while regressing substantially, or improve significantly while still remaining outside its target.

Healthy does not mean unchanged, and improved does not necessarily mean healthy.

Production telemetry should know which release produced the behavior being observed.

Release identity, deployment time, feature state, and relevant experiment context turn investigations from timeline archaeology into attributable engineering work.

A metric becomes much more actionable when it can be attached to the change that moved it.

Cache behavior can drift because of route changes, key changes, market dimensions, TTL changes, revalidation behavior, or failed invalidation.

Operators should be able to distinguish healthy dynamic behavior from unexpected origin execution or incorrect reuse.

The objective is not maximum cache HIT. It is adherence to intended cache policy.

External browser execution should be admitted with the same discipline applied to first-party production code.

Business value, route scope, consent, execution timing, customer data, performance cost, failure behavior, and removal capability should all be understood before admission.

The browser should not become the place where organizational ownership disappears.

First-party and third-party JavaScript both consume customer network, CPU, memory, and interaction time.

Operational attribution distinguishes architecture regressions from external execution growth so the responsible system can be changed.

The customer pays the combined cost. Operators still need to know who introduced it.

Feature flags are useful for rollout, experiments, compatibility, and incident isolation, but each flag creates another branch in production behavior.

Meaningful flags therefore need ownership, defaults, observability, and a defined removal or review condition.

Temporary control should not become permanent complexity.

Production can change because Shopify, a CMS, search system, analytics SDK, third-party script, browser, CDN, or runtime changed independently of the storefront repository.

Dependency changes should therefore be evaluated against their customer task, fallback behavior, performance, and integration contract.

A dependency upgrade is part of the storefront release surface even when it is owned elsewhere.

Shopify is intentionally part of the architecture, so API, Markets, checkout, customer, versioning, and platform changes deserve review.

The useful question is not whether Shopify published a changelog. It is whether a change alters commerce ownership, freshness, identity, checkout, market context, or another architectural assumption.

Platform change matters when it changes an architectural boundary, not merely because a changelog was published.

React, TanStack Start, Cloudflare Workers, and other current implementation layers will continue to evolve.

Upgrades should preserve rendering policy, server/client boundaries, route loading, caching, observability, runtime compatibility, and failure behavior rather than inheriting new defaults blindly.

Upgrade the implementation without accidentally redesigning the system.

Real-user metrics naturally change with geography, campaigns, devices, seasonality, and traffic mix.

Repeated synthetic measurement across representative routes provides a controlled reference that can help separate system change from population change.

Field data tells us what customers experienced. Synthetic continuity helps explain whether the system itself moved.

HTTP availability and good Core Web Vitals do not establish that cart, checkout, customer, market, pricing, discount, and commerce API behavior remain correct.

Commerce health therefore deserves first-class signals alongside infrastructure and performance monitoring.

A commerce storefront is healthy when customers can complete commerce correctly, not merely when servers return 200.

Consent, event schemas, analytics SDKs, tagging, checkout integration, and campaign tooling can break measurement while commerce itself continues to operate.

Shopify transaction truth should therefore remain comparable with the measurement systems used for business decisions.

Measurement correctness can regress independently from storefront correctness.

Graceful degradation can make a dependency outage almost invisible externally while the system remains internally unhealthy.

Stale content, search fallback, default personalization, open circuits, buffered analytics, and disabled third parties should remain visible operationally until the original capability has recovered.

A successful fallback protects the customer. It does not close the incident.

Not every metric movement should page an operator.

Alerts should represent conditions where customer impact, commerce correctness, SLOs, dependencies, fallbacks, analytics, releases, or other critical behavior requires an operational decision.

A dashboard explains the system. An alert asks for action.