Shopify Hydrogen vs Next.js: A Decision Guide

Start with fit, not framework labels

The Storefront API is Shopify’s interface for accessing commerce capabilities in a custom buyer experience, and it does not require a particular frontend framework. That means the first decision is not whether Shopify works with Hydrogen or Next.js; it is whether the framework, integration workflow, deployment model, and maintenance ownership fit the storefront you intend to operate.

Shopify describes the Storefront API as a way to use admin-managed commerce data while building a custom buyer experience. The API exposes capabilities such as displaying products and collections, cart operations, and contextual pricing. Treat that shared commerce interface as the starting point, then compare what each frontend workflow would require from your team.

Write down the storefront requirements before comparing implementation approaches. Include the buyer journeys, data and authentication needs, deployment environment, existing engineering tools, and the people responsible for releases and ongoing fixes. This prevents a familiar framework from being chosen before anyone has checked whether it supports the required operating model.

For Next.js, turn assumptions into verification questions: how will your team connect to the Storefront API, where will server-side work run, how will deployment and secrets be managed, and which runtime constraints matter? Check the answers against the current Next.js and hosting documentation rather than inferring capabilities from the framework name.

What Shopify’s Hydrogen workflow includes

Hydrogen has a documented Shopify path that connects a Hydrogen app to a storefront through a GitHub repository, with environments containing deployments. Use this workflow as a concrete baseline when comparing how much of the storefront lifecycle you want Shopify’s documented tooling to cover.

When creating a Hydrogen app through the storefront flow, a developer can start from a Hydrogen template and choose JavaScript or TypeScript. For an existing codebase, check how much of your current structure and tooling can be carried forward before deciding whether to start from a template or connect a repository.

A Hydrogen storefront is linked to one Hydrogen app through a GitHub repository, and storefronts can have multiple environments containing deployments. When an existing repository is connected to a Hydrogen storefront, Shopify opens a pull request for an Oxygen deployment workflow; merging that pull request starts continuous deployment to Oxygen.

Oxygen is a worker-based runtime for hosting Hydrogen storefronts at the edge. The workflow gives teams a specific deployment route to evaluate, but it should not replace a requirements review: map environments, release approvals, secrets, monitoring, and rollback ownership before treating any deployment path as ready for production.

Compare Shopify integration and API access

Compare the frameworks against the commerce features the storefront actually needs, then identify which API access and token setup each feature requires. This avoids a common planning mistake: treating “the Storefront API works” as proof that every buyer journey can be implemented with the same access pattern.

Tokenless Storefront API access allows queries without an access token for products, collections, selling plans, search, pages, blogs, articles, and cart read/write, subject to a query-complexity limit of 1,000. Check that scope against your feature list, and validate query complexity as you shape requests rather than assuming that a set of individually necessary fields will fit together.

Some Storefront API capabilities require token-based authentication, including product tags, metaobjects and metafields, Online Store navigation menus, and customers. Mark these requirements explicitly in the architecture so that token-dependent work is not discovered late in implementation.

Shopify’s guidance on private Storefront API tokens For either frontend choice, decide where private credentials will live and how developers will avoid accidentally placing them in browser-delivered code, logs, or shared configuration.

The Headless channel supports headless and self-hosted Hydrogen experiences without requiring a custom app, and it provides a place to create and manage Storefront API tokens and multiple custom storefronts. It also includes channel features such as product publishing, order attribution, and sales reporting; order attribution is at the channel level. A shop can have at most 100 active storefronts and access tokens.

Use those details to check operational fit, not just API coverage. Map who creates and rotates access tokens, how a storefront is represented for publishing and reporting, and whether your planned storefronts and tokens fit the documented limit. Confirm those responsibilities before splitting work across teams or environments.

Compare deployment and runtime responsibilities

Deployment fit is about the runtime your application needs and the work your team is prepared to own, not a generic claim that one framework is easier to host. Use Hydrogen and Oxygen’s documented setup as a concrete option, and verify Next.js runtime, hosting, and deployment details against the documentation for the exact setup you are considering.

Hydrogen projects include a local development server by default, and it closely mirrors Oxygen’s production runtime; both are based on Cloudflare’s open-source workerd project. That gives teams a documented development-to-production relationship to assess, but it is still important to test the project’s real integrations and deployment configuration rather than relying on a local run alone.

Oxygen’s supported JavaScript-standard web APIs Before committing to a runtime, inventory dependencies and application code that assume specific server or platform behavior, then test those assumptions in the target environment.

There are also specific Oxygen Cache API constraints: it does not support the caches.default API, and direct Cache API operations require HTTPS request URLs. If caching is central to the storefront, test the required cache operations early and document the expected behavior for local development and production.

For a self-hosted Hydrogen deployment or a Next.js option, compare the actual operating model: who owns infrastructure configuration, deploy permissions, secrets, runtime upgrades, incident response, and release checks? The answer may favor continuity with an established team workflow, or it may justify adopting a different workflow if the current one does not meet the storefront’s needs.

Include API maintenance and team ownership

A headless storefront remains an operating system to maintain after launch, so include API upkeep, deployment ownership, and knowledge transfer in the framework decision. Estimate the work by tracing the tasks from a commerce change to a tested, deployed buyer experience, and name the person or team accountable for each handoff.

The Storefront API is versioned, releases new versions four times a year, and Shopify recommends updating requests to the latest stable version each quarter. Add version review and request testing to the team’s maintenance process, and decide how the team will discover and assess changes before an update becomes urgent.

Then compare the operating work that remains regardless of framework: reviewing API access, protecting credentials, testing storefront journeys, validating deployment behavior, and keeping the codebase understandable to the people who will support it. A stack that fits the team’s existing skills can reduce handoffs, but only if the team can also meet the storefront’s runtime and commerce requirements.

For Next.js, verify its Shopify integration approach and the deployment and runtime details relevant to your target environment. Keep the comparison evidence-based: record what the documentation confirms, what your team has tested, and which questions still need a prototype or architecture decision.

Decision checklist: match the stack to the storefront

Choose the frontend after matching the storefront’s requirements to its integration path and the team’s operating model. Use this checklist to turn the discussion into decisions you can validate before committing to implementation.

• List the commerce capabilities and customer journeys the storefront must support; map each to the required Storefront API access and authentication.
• Record the existing frontend skills, repository conventions, release process, and people who will own ongoing maintenance.
• For Hydrogen, assess the app, repository, environments, and Oxygen or self-hosted deployment workflow against your requirements.
• For Next.js, verify Shopify integration, runtime, hosting, deployment, and secret-management details in the relevant documentation.
• Identify runtime assumptions and test any required APIs, caching behavior, and deployment configuration in the target environment.
• Assign ownership for token security, API version review, storefront releases, and ongoing support.