> ## Documentation Index
> Fetch the complete documentation index at: https://weaverse.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Weaverse for Next.js

> Build a Shopify Hydrogen storefront on the Next.js App Router with @weaverse/next.

# 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](https://github.com/Shopify/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](https://github.com/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:

| | `@weaverse/hydrogen` (React Router) | `@weaverse/next` (Next.js) |
| - | - | - |
| Server client | `context.weaverse`, injected into every route loader | Created by your app per request with `createWeaverseNextServerClient()` |
| Component registry | One registry | A client registry (rendering) and a server registry (schemas and loaders), split by React Server Components |
| Root theme store | `withWeaverse()` around the root | `WeaverseNextRootProvider` in `app/layout.tsx` |
| Page rendering | `WeaverseHydrogenRoot` in a route | `WeaverseNextRenderer` inside a client boundary |
| Loader revalidation | React Router `shouldRevalidate` | A route handler created with `createWeaverseNextRevalidateHandler()` |
| Routes | Shopify URL convention | Any routes your app serves; declare the ones that differ in the theme schema's `routes` |

## Requirements

* A Shopify store with Storefront API access from the [Headless channel](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/manage-headless-channels): a private token for server reads, and the public token Studio uses to open default templates (see [Studio integration](/docs/nextjs/studio)).
* 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.

<Note>
  [Forward](/docs/hydrogen-themes/forward), the Weaverse Next.js starter theme, runs in production on `@weaverse/next@1.0.0` with Next.js 16, React 19 and the Hydrogen SDK (preview).
</Note>

## 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](/docs/nextjs/studio).
* **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](/docs/nextjs/markets-translations).
* **Custom pages and SEO**: custom pages, sitemap data, and page SEO mapped to Next `Metadata`. See [Rendering pages](/docs/nextjs/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

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/nextjs/quickstart">
    Start from Forward or add Weaverse to an existing Next app.
  </Card>

  <Card title="Rendering pages" icon="file" href="/docs/nextjs/rendering-pages">
    Load and render Weaverse pages in App Router routes.
  </Card>

  <Card title="Data fetching" icon="database" href="/docs/nextjs/data-fetching">
    Section loaders, caching and design mode.
  </Card>

  <Card title="Studio integration" icon="wand-magic-sparkles" href="/docs/nextjs/studio">
    Connect Studio, revalidate items and declare routes.
  </Card>

  <Card title="Markets & translations" icon="globe" href="/docs/nextjs/markets-translations">
    Localized pages and theme copy.
  </Card>

  <Card title="API reference" icon="code" href="/docs/nextjs/api-reference">
    Everything `@weaverse/next` exports.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.