Integrating Weaverse into an Existing Hydrogen Project

npm install @weaverse/hydrogen@^6.1.0

import { WeaverseClient, withWeaverse, useThemeSettings } from "@weaverse/hydrogen/react-router";

# .env

# Required
WEAVERSE_PROJECT_ID="your-project-id"

# Optional
# WEAVERSE_API_KEY="your-weaverse-api-key"
# WEAVERSE_HOST="https://studio.weaverse.io"

// env.d.ts
/// <reference types="vite/client" />
/// <reference types="react-router" />
/// <reference types="@shopify/oxygen-workers-types" />
import type { WeaverseEnv } from "@weaverse/hydrogen/react-router";
import type { AppContext } from "./app/.server/context";

declare global {
  interface Env extends WeaverseEnv {
    SESSION_SECRET: string;
    PUBLIC_STORE_DOMAIN: string;
    PUBLIC_STOREFRONT_API_TOKEN?: string;
    PRIVATE_STOREFRONT_API_TOKEN?: string;
    PUBLIC_STOREFRONT_ID?: string;
    PUBLIC_CHECKOUT_DOMAIN: string;
    WEAVERSE_PROJECT_ID: string;
    WEAVERSE_API_KEY?: string;
    WEAVERSE_HOST?: string;
    // ... the rest of your variables
  }
}

declare module "react-router" {
  // `server.ts` copies the app context onto React Router's context (Step 5)
  interface AppLoadContext extends AppContext {}
  interface RouterContextProvider extends AppContext {}
}

// app/weaverse/schema.server.ts
import type { WeaverseThemeSchema } from "@weaverse/hydrogen/react-router";
import packageJson from "../../package.json" with { type: "json" };
import { DEFAULT_LOCALE, SUPPORTED_LOCALES } from "~/utils/locale";

export const themeSchema: WeaverseThemeSchema = {
  info: {
    version: packageJson.version,
    author: "Your Store Name",
    name: "Your Theme Name",
    authorProfilePhoto: "",
    documentationUrl: "https://docs.weaverse.io",
    supportUrl: "https://help.weaverse.io/",
  },
  // Optional; required for markets and the Translation Manager
  i18n: {
    urlStructure: "url-path",
    defaultLocale: DEFAULT_LOCALE,
    shopLocales: SUPPORTED_LOCALES,
  },
  settings: [
    {
      group: "Layout",
      inputs: [
        {
          type: "range",
          label: "Page width",
          name: "pageWidth",
          configs: { min: 1000, max: 1600, step: 10, unit: "px" },
          defaultValue: 1280,
        },
      ],
    },
    // ... more groups: colors, typography, header, footer
  ],
};

// app/weaverse/components.ts
import type { WeaverseComponent } from "@weaverse/hydrogen/react-router";
import * as Heading from "~/components/heading";
import * as FeaturedProducts from "~/sections/featured-products";
import * as HeroImage from "~/sections/hero-image";

export const components: WeaverseComponent[] = [Heading, HeroImage, FeaturedProducts];

// app/weaverse/style.tsx
import { useThemeSettings } from "@weaverse/hydrogen/react-router";

export function GlobalStyle() {
  const settings = useThemeSettings();
  if (!settings) return null;
  return (
    <style
      id="global-theme-style"
      suppressHydrationWarning
      dangerouslySetInnerHTML={{
        __html: `:root { --page-width: ${settings.pageWidth}px; }`,
      }}
    />
  );
}

// app/weaverse/index.tsx
import { WeaverseHydrogenRoot, type WeaverseLoaderData } from "@weaverse/hydrogen/react-router";
import { GenericError } from "~/components/root/generic-error";
import { components } from "./components";

export function WeaverseContent() {
  return <WeaverseHydrogenRoot components={components} errorComponent={GenericError} />;
}

export function validateWeaverseData(weaverseData: WeaverseLoaderData) {
  if (
    !weaverseData?.page?.id ||
    (weaverseData?.page?.id?.includes("fallback") &&
      !weaverseData?.configs?.requestInfo?.queries?.isDesignMode)
  ) {
    throw new Response(null, { status: 404 });
  }
}

// app/.server/context.ts
import { WeaverseClient } from "@weaverse/hydrogen/react-router";
import { AppSession } from "~/.server/session";
import { createRequestStorefront, resolveRequestLocale } from "~/.server/storefront";
import { components } from "~/weaverse/components";
import { themeSchema } from "~/weaverse/schema.server";

export async function createAppContext(
  request: Request,
  env: Env,
  executionContext: ExecutionContext,
) {
  const waitUntil = executionContext.waitUntil.bind(executionContext);
  const [cache, session] = await Promise.all([
    caches.open("hydrogen"),
    AppSession.init(request, [env.SESSION_SECRET]),
  ]);
  const storefront = createRequestStorefront({ request, env, cache, waitUntil });

  const weaverse = new WeaverseClient({
    storefront, // the request-scoped Hydrogen 2026.10 Storefront client
    locale: resolveRequestLocale(request), // optional, 6.1.0+
    env,
    cache,
    waitUntil,
    request,
    themeSchema,
    components,
  });

  return { env, cache, waitUntil, session, storefront, weaverse };
}

export type AppContext = Awaited<ReturnType<typeof createAppContext>>;

// server.ts
import { handleShopifyRedirects, handleShopifyRoutes } from "@shopify/hydrogen";
import { createRequestHandler, RouterContextProvider } from "react-router";
import * as serverBuild from "virtual:react-router/server-build";
import { cartHandlers } from "~/.server/cart";
import { createAppContext } from "~/.server/context";
import { routeTemplates } from "~/utils/route-templates";

const handleRequest = createRequestHandler(serverBuild, process.env.NODE_ENV);

export default {
  async fetch(request: Request, env: Env, executionContext: ExecutionContext): Promise<Response> {
    try {
      // 1. Build the request context: session, Storefront client, WeaverseClient
      const appContext = await createAppContext(request, env, executionContext);
      const { session, storefront } = appContext;
      const requestContext = storefront.requestContext;

      // 2. Let Hydrogen answer the routes it owns (/api/cart, /account/login, ...)
      const shopifyRoute = handleShopifyRoutes({
        request,
        requestContext,
        sessionManager: session,
        storefrontClient: storefront,
        routeTemplates,
        handlers: [cartHandlers /* , predictive search, Customer Account, ... */],
      });
      if (shopifyRoute) {
        const response = await shopifyRoute;
        await commitSession(response, appContext);
        return response;
      }

      // 3. Render the app. Loaders read context.storefront, context.weaverse, ...
      const routerContext = Object.assign(new RouterContextProvider(), appContext);
      const response = await handleRequest(request, routerContext);

      // 4. On a 404, look the path up in Shopify's URL redirects
      if (response.status === 404) {
        const redirect = await handleShopifyRedirects({
          request,
          storefrontClient: storefront,
          routeTemplates,
        });
        if (redirect) return redirect;
      }

      // 5. Commit the session, then apply Shopify's response headers
      await commitSession(response, appContext);
      requestContext.applyResponseHeaders(response.headers);
      return response;
    } catch (error) {
      console.error(error);
      return new Response("An unexpected error occurred", { status: 500 });
    }
  },
};

async function commitSession(
  response: Response,
  { session }: Awaited<ReturnType<typeof createAppContext>>,
) {
  const headers = new Headers((await session.commit()) ?? undefined);
  for (const [name, value] of headers) response.headers.append(name, value);
}

// app/utils/cache.ts
import { Cache } from "@shopify/hydrogen";

// Classic Hydrogen's implicit default: fresh for a second, stale for a day
export const CACHE_DEFAULT = Cache({ mode: "public", maxAge: 1, staleWhileRevalidate: 86_399 });
export const CACHE_SHORT = Cache.short();
export const CACHE_LONG = Cache.long();
export const CACHE_NONE = Cache.none();

// app/sections/featured-collections/index.tsx
import { gql } from "@shopify/hydrogen";
import type { WeaverseComponentLoaderArgs } from "@weaverse/hydrogen/react-router";
import { CACHE_DEFAULT } from "~/utils/cache";
import { unwrapStorefront } from "~/utils/storefront";

const COLLECTIONS_QUERY = gql(`
  query collectionsByIds($country: CountryCode, $language: LanguageCode, $ids: [ID!]!)
  @inContext(country: $country, language: $language) {
    nodes(ids: $ids) { ... on Collection { id title handle } }
  }
`);

export const loader = async ({ data, weaverse }: WeaverseComponentLoaderArgs<FeaturedCollectionsData>) => {
  const ids = data.collections?.map(
    (collection) => `gid://shopify/Collection/${collection.id}`,
  );
  if (!ids?.length) return [];
  const { nodes } = unwrapStorefront(
    await weaverse.storefront.graphql(COLLECTIONS_QUERY, {
      variables: { ids }, // $country and $language come from the request context
      cache: CACHE_DEFAULT,
    }),
  );
  // `nodes(ids:)` returns any `Node`, or null: keep the collections
  return nodes.filter((node) => Boolean(node && "id" in node));
};

// app/entry.server.tsx
import { isbot } from "isbot";
import { renderToReadableStream } from "react-dom/server";
import type { EntryContext, RouterContextProvider } from "react-router";
import { ServerRouter } from "react-router";
import { createContentSecurityPolicy, generateNonce, NonceProvider } from "~/utils/csp";
import { getWeaverseCsp } from "~/weaverse/csp";

export default async function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  reactRouterContext: EntryContext,
  context: RouterContextProvider,
) {
  const nonce = generateNonce();
  const header = createContentSecurityPolicy(nonce, getWeaverseCsp(request, context.env), {
    checkoutDomain: context.env?.PUBLIC_CHECKOUT_DOMAIN || context.env?.PUBLIC_STORE_DOMAIN,
    storeDomain: context.env?.PUBLIC_STORE_DOMAIN,
  });

  const body = await renderToReadableStream(
    <NonceProvider value={nonce}>
      <ServerRouter context={reactRouterContext} url={request.url} nonce={nonce} />
    </NonceProvider>,
    {
      nonce,
      signal: request.signal,
      onError(error) {
        console.error(error);
        responseStatusCode = 500;
      },
    },
  );

  if (isbot(request.headers.get("user-agent"))) {
    await Promise.race([body.allReady, new Promise((resolve) => setTimeout(resolve, 2000))]);
  }

  responseHeaders.set("Content-Type", "text/html");
  // Pilot ships report-only. Switch to "Content-Security-Policy" once your directives are complete.
  responseHeaders.set("Content-Security-Policy-Report-Only", header);

  return new Response(body, { headers: responseHeaders, status: responseStatusCode });
}

// app/root.tsx
import { withWeaverse } from "@weaverse/hydrogen/react-router";
import type { LoaderFunctionArgs } from "react-router";
import { Links, Meta, Outlet, Scripts, ScrollRestoration, useRouteLoaderData } from "react-router";
import { useNonce } from "~/utils/csp";
import { GlobalStyle } from "~/weaverse/style";

export type RootLoader = typeof loader;

export async function loader({ context }: LoaderFunctionArgs) {
  const weaverseTheme = await context.weaverse.loadThemeSettings();
  return {
    weaverseTheme,
    selectedLocale: context.storefront.i18n,
    // ... layout data, ShopifyScripts config, consent
  };
}

function App() {
  return <Outlet />;
}

export const Layout = withWeaverse(function RootLayout({ children }: { children: React.ReactNode }) {
  const nonce = useNonce();
  const data = useRouteLoaderData<RootLoader>("root");

  return (
    // Pilot sets `lang` from its market list (`locale.hreflang`)
    <html lang="en">
      <head>
        {/* ... meta, <ShopifyScripts nonce={nonce} ... /> */}
        <Meta />
        <Links />
        <GlobalStyle />
      </head>
      <body>
        {/* ... CartProvider, header */}
        <main>{children}</main>
        {/* ... footer */}
        <ScrollRestoration nonce={nonce} />
        <Scripts nonce={nonce} />
      </body>
    </html>
  );
});

export default App;

// app/routes.ts
import { index, prefix, type RouteConfig, route } from "@react-router/dev/routes";

export default [
  ...prefix(":locale?", [
    index("routes/home.tsx"),
    route("products/:productHandle", "routes/products/product.tsx"),
    route("pages/:pageHandle", "routes/pages/regular-page.tsx"),
    // ... your other routes
    route("*", "routes/catch-all.tsx"), // Weaverse custom pages
  ]),
] satisfies RouteConfig;

// app/routes/home.tsx
import { gql } from "@shopify/hydrogen";
import { getWeaverseSeoMeta, type PageType } from "@weaverse/hydrogen/react-router";
import type { LoaderFunctionArgs, MetaArgs } from "react-router";
import { CACHE_LONG, routeHeaders } from "~/utils/cache";
import { unwrapStorefront } from "~/utils/storefront";
import { validateWeaverseData, WeaverseContent } from "~/weaverse";

export const headers = routeHeaders;

export async function loader({ params, context }: LoaderFunctionArgs) {
  const { pathPrefix } = context.storefront.i18n;
  const locale = pathPrefix?.slice(1) || "";
  let type: PageType = "INDEX";

  if (params.locale && params.locale.toLowerCase() !== locale) {
    // Not a market prefix: a Weaverse custom page at the root
    type = "CUSTOM";
  }

  const [weaverseData, { shop }] = await Promise.all([
    context.weaverse.loadPage({ type }),
    context.storefront.graphql(SHOP_QUERY, { cache: CACHE_LONG }).then(unwrapStorefront),
  ]);
  validateWeaverseData(weaverseData);

  return { shop, weaverseData };
}

export const meta = ({ data }: MetaArgs<typeof loader>) => getWeaverseSeoMeta(data?.weaverseData);

export default function Homepage() {
  return <WeaverseContent />;
}

const SHOP_QUERY = gql(`
  query shop($country: CountryCode, $language: LanguageCode)
  @inContext(country: $country, language: $language) {
    shop { name description }
  }
`);

// app/routes/products/product.tsx
import { getSelectedProductOptions } from "@weaverse/hydrogen/react-router";
import type { LoaderFunctionArgs } from "react-router";
import { PRODUCT_QUERY } from "~/graphql/queries";
import { CACHE_DEFAULT } from "~/utils/cache";
import { unwrapStorefront } from "~/utils/storefront";
import { WeaverseContent } from "~/weaverse";

export async function loader({ params, request, context }: LoaderFunctionArgs) {
  const { productHandle: handle } = params;
  const { storefront, weaverse } = context;
  // Hydrogen's selected options, without Weaverse's Studio query params
  const selectedOptions = getSelectedProductOptions(request);

  const [{ shop, product }, weaverseData] = await Promise.all([
    storefront
      .graphql(PRODUCT_QUERY, { variables: { handle, selectedOptions }, cache: CACHE_DEFAULT })
      .then(unwrapStorefront),
    weaverse.loadPage({ type: "PRODUCT", handle }),
  ]);

  if (!product?.id) {
    throw new Response("product", { status: 404 });
  }

  return { shop, product, weaverseData, selectedOptions };
}

export default function Product() {
  return <WeaverseContent />;
}

npm run build    # react-router build: writes dist/client and dist/server
npx shopify hydrogen deploy --assets-dir dist/client --worker-dir dist/server