The Shopify theme vs headless decision starts with a specific limitation in the current store. A slow search panel, an unusual buying flow and a difficult editorial workflow are different problems. I would test whether a theme change or embedded feature can solve the actual problem before proposing a replacement storefront.
1. Separate a feature problem from a storefront problem
My SwiftSearch implementation installs as a theme app embed. Its documented loading split is a 4.5 KB gzipped core and an 18 KB interface fetched when focus or hover signals search intent. It adds search behavior without requiring a new storefront architecture.
The Dahlia AI case study describes another boundary: a vanilla JavaScript storefront widget, a separate Node and Express backend, and an operator CMS. A separate backend did not require replacing the surrounding Shopify theme. These are documented project choices, not evidence that every feature belongs in a widget.
Shopify's theme app extension documentation describes app blocks and app embeds for integrating features into themes. Include this option explicitly in an architecture review. Otherwise the discussion can jump from a limited theme setting directly to rebuilding the entire customer experience.
Write down the failing task first: “customers cannot compare the required product options,” for example. That is an illustrative requirement. “We need a modern stack” does not identify what the customer or merchant needs to do differently.
2. Compare three options against the same requirement
Shopify documents headless build options, including Hydrogen and other custom stacks. The availability of an option does not establish that it fits a particular store. A useful comparison needs a small proof of the difficult requirement in each plausible approach.
I would use this worksheet in a discovery session. Record a working example, a documented constraint or an unresolved question for each option. Do not turn an untested assumption into a green check mark.
| Requirement | Theme change to investigate | Embedded feature to investigate | Headless evidence needed |
|---|---|---|---|
| Better product search | Existing search template and app options | Dedicated search panel | Required search journey works with chosen data source |
| Guided product selection | Template and product configuration changes | Focused configurator | Full option, cart and checkout handoff works |
| Distinct editorial experience | Sections, templates and current content workflow | Limited interactive module | Editors can preview and publish representative pages |
| Slow shopping interactions | Measured image and script improvements | Defer optional interface work | The same journey improves under comparable conditions |
| Multiple storefront experiences | Current theme and market workflows | Shared feature where appropriate | Ownership of content, routing and integrations is clear |
Record the smallest implementation that satisfies the requirement and the remaining limitations. A working prototype can still reveal an unacceptable merchant workflow. Include the person who changes promotions and product content, not only the engineers writing the storefront.
If performance is the main reason for the review, begin with the Shopify theme speed audit. It defines a repeatable journey and testing conditions. A framework label is not a measurement of loading or responsiveness.
3. Test the merchant's week as well as the shopper's minute
Ask someone who operates the store to complete representative tasks in the proposed setup. Change a banner, create a collection, publish a product, preview a campaign and correct a navigation link. Record every step that needs a developer or an additional deployment.
Inventory the current integrations before the proof of concept. For each app, establish which behavior depends on the existing theme and what a custom storefront would need instead. Treat unverified compatibility as an open question that needs testing or confirmation from its official documentation.
Then assign ownership of preview environments, deployments, monitoring and recovery. “The agency will handle it” is incomplete unless the actual support arrangement and response expectations are defined. A named owner and a repeatable recovery procedure are more useful than an optimistic maintenance estimate.
For a contained interactive feature, the embeddable widget guide offers a narrower implementation pattern. Compare its installation, isolation and cleanup requirements with those of a whole storefront. The boundary should follow the task, not a preference for one framework.
4. Make search visibility part of the migration proof
Shopify's Hydrogen SEO guide provides tools for search-related metadata. Having those tools available is only the beginning of an implementation review. The project still needs acceptance checks against the pages it intends to publish.
I would create a route inventory before migration: current URLs, intended destinations, important incoming links and pages that must remain available. Record titles, canonical URLs and the page content delivered to a crawler. Check product and collection pagination as well as the homepage.
For each changed URL, specify the intended redirect and verify it after deployment. For each retained URL, compare the expected content and metadata with the live response. Also review sitemap membership and accidental indexing restrictions in the deployed environment.
These are proposed migration checks, not a promise that rankings will stay unchanged. Keep a dated baseline from Search Console and compare indexing and search performance after launch. Without account data, a technical crawl can confirm page behavior but cannot establish Google's actual indexing decisions.
5. Choose a reversible first milestone
Before approving a larger build, define one difficult shopper journey and one merchant publishing task that the proposal must support. Set the conditions, reviewers and failure criteria in advance. Include the cart handoff and an unavailable-product case instead of testing only a polished landing page.
Save the current implementation and write down the restoration procedure. If the feature can be introduced independently, establish what happens when it is disabled or its backend fails. If the storefront changes as a whole, rehearse the deployment and rollback with the people responsible for operating it.
The decision record should contain the demonstrated requirement, options tested, evidence collected and outstanding costs or integration questions. That is enough to explain the choice to a merchant later, even if the preferred technology changes.
Bring that record to a storefront architecture review. I would start with the blocked task and the smallest useful proof, then decide whether the store needs a theme improvement, a focused feature or a custom storefront.