​

Weaverse for Next.js

@weaverse/next is the Weaverse adapter for the Next.js App Router. It renders Weaverse pages in a Next storefront, connects them to Weaverse Studio for visual editing, and runs your section loaders on the server. Version 1.0.0 is the first stable release. A Next.js storefront is still a Shopify Hydrogen storefront. Hydrogen is Shopify’s framework-agnostic toolkit for headless commerce, and the React Router template is only one way to use it: the Hydrogen README lists Vercel Shop, a Next.js storefront built on Hydrogen and maintained by Vercel, alongside it. Each layer owns one job:

• Shopify owns commerce. Products, collections, cart, checkout, customer accounts and markets come from your store through the Hydrogen SDK (@shopify/hydrogen) and the Storefront API.
• Next.js owns the app. Routing, Server Components, caching and metadata.
• Weaverse owns the pages. Sections, theme settings, translations and visual editing in Studio.

​

React Router or Next.js?

Both are Hydrogen storefronts on Shopify, so your component schemas, input settings and theme settings work the same way. Weaverse ships one adapter per framework; pick the one your storefront runs on:

• @weaverse/hydrogen for the Hydrogen React Router framework, for example a storefront deployed to Oxygen. The name predates Hydrogen becoming framework-agnostic.
• @weaverse/next for the Next.js App Router, for example a storefront deployed to Vercel.

What changes is how the framework hands Weaverse a request and renders the page:

​

Requirements

• A Shopify store with Storefront API access from the Headless channel: a private token for server reads, and the public token Studio uses to open default templates (see Studio integration).
• A Next.js App Router app that reads from Shopify, typically through the Hydrogen SDK (npx @shopify/hydrogen@latest setup). Peer dependencies: next >= 14, react >= 19, react-dom >= 19.
• A Weaverse project.

​

What 1.0 supports

• Page rendering: home, product, collection, all products, page, article and custom pages, with section loaders on the server.
• Studio editing: connect, select, edit and reorder sections in Weaverse Studio, with live theme settings.
• Per-item revalidation: a resource picker edit re-runs only that section’s loader. See Studio integration.
• Theme settings: one root store shared by global components (header, footer) and every page.
• Markets and translations: localized pages per market and the Translation Manager. See Markets & translations.
• Custom pages and SEO: custom pages, sitemap data, and page SEO mapped to Next Metadata. See Rendering pages.
• Theme routes: tell Studio which paths your storefront uses when they differ from Shopify’s.

​

Known limitations

• publicEnv in the root layout. The SDK attaches publicEnv to the theme settings response only in design mode, which it reads from ?isDesignMode=true. A Next layout receives no search params, so pass publicEnv to WeaverseNextRootProvider yourself. Studio needs PUBLIC_STORE_DOMAIN and PUBLIC_STOREFRONT_API_TOKEN from it to open your store’s default product, collection and page.
• Shopify redirects and request handling are part of your app, not the SDK. Add the redirects your storefront needs in next.config or your proxy.

​

Next steps