npx @weaverse/cli@latest create \
  --template=pilot \
  --project-id="your-project-id" \
  --project-name=my-storefront

npm install @shopify/hydrogen@^2026.10.2 @weaverse/hydrogen@^6.0.0 \
  react-router@7.18.5 @react-router/dev@7.18.5
npm install -D gql.tada @types/node @shopify/mini-oxygen@^4.2.3 @shopify/cli@^4.9.4
npm uninstall @shopify/hydrogen-codegen @graphql-codegen/cli
rm codegen.ts storefront-api.generated.d.ts customer-account-api.generated.d.ts

{
  "scripts": {
    "build": "shopify hydrogen build --codegen",
    "dev": "react-router typegen && shopify hydrogen dev --codegen --port 3456",
    "preview": "shopify hydrogen preview --build",
    "typecheck": "tsc --noEmit",
    "codegen": "shopify hydrogen codegen"
  }
}

{
  "scripts": {
    "build": "react-router build",
    "dev": "hydrogen skills check --mode=warn && vite dev --port 3456",
    "dev:https": "hydrogen skills check --mode=warn && vite dev --port 3456",
    "preview": "react-router build && vite preview --port 3456",
    "start": "vite preview --port 3456",
    "typecheck": "react-router typegen && tsc --noEmit && hydrogen gql check --fail-on-warn",
    "deploy": "shopify hydrogen deploy --assets-dir dist/client --worker-dir dist/server"
  }
}

// Before
import { hydrogen } from "@shopify/hydrogen/vite";

plugins: [hydrogen(), oxygen(), reactRouter(), tailwindcss()],

// After
import { localHttps } from "@shopify/hydrogen/vite";
import { oxygen } from "@shopify/mini-oxygen/vite";

plugins: [
  // `npm run dev:https` serves https://local.tryhydrogen.dev
  localHttps({ enabled: process.env.npm_lifecycle_event === "dev:https" }),
  ...oxygen(), // returns an array: spread it
  reactRouter(),
  tailwindcss(),
],
ssr: {
  optimizeDeps: {
    // React and React Router must be pre-bundled for the workerd SSR runtime
    include: [
      "react",
      "react/jsx-runtime",
      "react/jsx-dev-runtime",
      "react-dom",
      "react-dom/server",
      "react-router",
      "react-router > cookie",
      "react-router > set-cookie-parser",
    ],
  },
},

import type { Config } from "@react-router/dev/config";

export default {
  appDirectory: "app",
  // `shopify hydrogen deploy --assets-dir dist/client --worker-dir dist/server`
  // reads this directory; React Router's default is `build/`.
  buildDirectory: "dist",
  ssr: true,
  subResourceIntegrity: false,
  future: {
    v8_middleware: true,
    v8_splitRouteModules: true,
    v8_viteEnvironmentApi: false,
    unstable_optimizeDeps: true,
    v8_passThroughRequests: true,
    v8_trailingSlashAwareDataRequests: true,
  },
} satisfies Config;

{
  "compilerOptions": {
    "types": ["@shopify/oxygen-workers-types", "node", "react-router", "vite/client"],
    "paths": { "~/*": ["./app/*"] },
    "plugins": [{ "name": "@shopify/hydrogen/ts-plugin" }]
  }
}

# Generated by @shopify/hydrogen/ts-plugin
storefront-graphql-env.d.ts
customer-account-graphql-env.d.ts

npx @weaverse/cli@latest migrate v6 --dry-run

npx @weaverse/cli@latest migrate v6
git diff

// server.ts
import * as remixBuild from "virtual:react-router/server-build";
import { storefrontRedirect } from "@shopify/hydrogen";
import { createRequestHandler } from "@shopify/hydrogen/oxygen";
import { createHydrogenRouterContext } from "~/.server/context";

export default {
  async fetch(request: Request, env: Env, executionContext: ExecutionContext) {
    const hydrogenContext = await createHydrogenRouterContext(request, env, executionContext);
    const handleRequest = createRequestHandler({
      build: remixBuild,
      mode: process.env.NODE_ENV,
      getLoadContext: () => hydrogenContext,
    });

    const response = await handleRequest(request);
    if (hydrogenContext.session.isPending) {
      response.headers.set("Set-Cookie", await hydrogenContext.session.commit());
    }
    if (response.status === 404) {
      return storefrontRedirect({ request, response, storefront: hydrogenContext.storefront });
    }
    return response;
  },
};

// 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, createPilotCartHandlers } from "~/.server/cart";
import { createAppContext } from "~/.server/context";
import { getCustomerAccountHandlers } from "~/.server/customer-account";
import { predictiveSearchHandlers } from "~/.server/predictive-search";
import { routeTemplates } from "~/utils/route-templates";

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

export default {
  async fetch(request: Request, env: Env, executionContext: ExecutionContext) {
    try {
      // 1. The request context and clients
      const appContext = await createAppContext(request, env, executionContext);
      const { session, storefront } = appContext;
      const requestContext = storefront.requestContext;

      // 2. Routes Hydrogen owns: /api/cart, predictive search, /account/login, ...
      const shopifyRoute = handleShopifyRoutes({
        request,
        requestContext,
        sessionManager: session,
        storefrontClient: storefront,
        routeTemplates,
        handlers: [
          createPilotCartHandlers({
            getCustomerAccessToken: appContext.customerAccount.getAccessToken,
          }),
          cartHandlers,
          predictiveSearchHandlers,
          getCustomerAccountHandlers(env),
        ],
      });
      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/.server/context.ts
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 customerAccount = createCustomerAccount({ env, request, session, storefront });
  const weaverse = new WeaverseClient({ /* Step 5 */ });

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

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

import {
  type CachingStrategy,
  createShopifyRequestContext,
  createStorefrontClient,
  type PublicStorefrontClient,
  type RequestScopedPrivateStorefrontClient,
} from "@shopify/hydrogen";

// The bare client types drop `cache` from `graphql()` options; carry it.
type StorefrontCallOptions = { cache?: CachingStrategy };

export function createRequestStorefront({ request, env, cache, waitUntil }) {
  const i18n = getRequestI18n(request); // { country, language, pathPrefix, ... }
  const buyerIp = getBuyerIp(request.headers); // `oxygen-buyer-ip`, then proxy headers
  const config = {
    storeDomain: env.PUBLIC_STORE_DOMAIN,
    storefrontId: env.PUBLIC_STOREFRONT_ID || undefined,
    cache,
    waitUntil,
  };

  if (env.PRIVATE_STOREFRONT_API_TOKEN && buyerIp) {
    return createStorefrontClient({
      type: "private",
      requestContext: createShopifyRequestContext({ request, i18n, buyerIp }),
      config: { ...config, privateStorefrontToken: env.PRIVATE_STOREFRONT_API_TOKEN },
    });
  }

  return createStorefrontClient({
    type: "public",
    requestContext: createShopifyRequestContext({ request, i18n }),
    config: { ...config, publicStorefrontToken: env.PUBLIC_STOREFRONT_API_TOKEN },
  });
}

import type { HydrogenEnv, HydrogenSessionData } from "@shopify/hydrogen";
import type { WeaverseClient } from "@weaverse/hydrogen";
import type { createHydrogenRouterContext } from "./app/.server/context";

declare global {
  interface Env extends HydrogenEnv {
    // ...
  }
}

declare module "react-router" {
  interface AppLoadContext extends Awaited<ReturnType<typeof createHydrogenRouterContext>> {
    weaverse: WeaverseClient;
    // ...
  }
  interface SessionData extends HydrogenSessionData {}
}

/// <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 {
  /** The Oxygen worker bindings (`.env` locally). */
  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;
    SHOP_ID: string;
    PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID: string;
    WEAVERSE_PROJECT_ID: string;
    // ...
  }
}

declare module "react-router" {
  interface AppLoadContext extends AppContext {}
  interface RouterContextProvider extends AppContext {}
}

import { WeaverseClient } from "@weaverse/hydrogen";

const weaverse = new WeaverseClient({
  ...hydrogenContext,
  request,
  cache,
  themeSchema,
  components,
});
Object.assign(hydrogenContext, { weaverse });

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

const weaverse = new WeaverseClient({
  storefront, // the request-scoped Storefront client from Step 4
  env,
  cache,
  waitUntil,
  request,
  customerAccount, // optional; passed through to section loaders
  themeSchema,
  components,
});

import type { ProductQuery } from "storefront-api.generated";

const PRODUCT_QUERY = `#graphql
  query product($country: CountryCode, $language: LanguageCode, $handle: String!)
  @inContext(country: $country, language: $language) {
    product(handle: $handle) { ...ProductDetails }
  }
  ${PRODUCT_FRAGMENT}
` as const;

const { product } = await storefront.query<ProductQuery>(PRODUCT_QUERY, {
  variables: {
    handle,
    country: storefront.i18n.country,
    language: storefront.i18n.language,
  },
  cache: storefront.CacheLong(),
});

import { gql, type StorefrontApi } from "@shopify/hydrogen";
import { CACHE_LONG } from "~/utils/cache";
import { unwrapStorefront } from "~/utils/storefront";

const PRODUCT_QUERY = gql(
  `
  query product($country: CountryCode, $language: LanguageCode, $handle: String!)
  @inContext(country: $country, language: $language) {
    product(handle: $handle) { ...ProductDetails }
  }
`,
  [PRODUCT_FRAGMENT], // fragments are passed, not interpolated
);

export type ProductQuery = StorefrontApi.ResultOf<typeof PRODUCT_QUERY>;

const { product } = await storefront
  .graphql(PRODUCT_QUERY, { variables: { handle }, cache: CACHE_LONG })
  .then(unwrapStorefront);

import { type ComponentLoaderArgs } from "@weaverse/hydrogen";
import type { CollectionsByIdsQuery } from "storefront-api.generated";

export const loader = async ({ data, weaverse }: ComponentLoaderArgs<FeaturedCollectionsData>) => {
  const { nodes } = await weaverse.storefront.query<CollectionsByIdsQuery>(COLLECTIONS_QUERY, {
    variables: { ids },
  });
  return nodes.filter(Boolean);
};

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 { nodes } = unwrapStorefront(
    await weaverse.storefront.graphql(COLLECTIONS_QUERY, {
      variables: { ids },
      cache: CACHE_DEFAULT,
    }),
  );
  return nodes.filter((node) => Boolean(node && "id" in node));
};

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

export default [
  route("robots.txt", "routes/seo/robots.ts"),
  layout("routes/market-guard-resources.ts", [
    ...prefix(":locale?", [
      route("sitemap.xml", "routes/seo/sitemap.ts"),
      route("discount/:code", "routes/others/discount-code.tsx"),
      route("cart/checkout", "routes/cart/checkout.tsx"),
      // ... other resource routes and `api/*`
    ]),
  ]),
  layout("routes/market-guard.ts", [
    ...prefix(":locale?", [
      index("routes/home.tsx"),
      route("products/:productHandle", "routes/products/product.tsx"),
      // ... other pages
      route("*", "routes/catch-all.tsx"), // Weaverse custom pages
    ]),
  ]),
] satisfies RouteConfig;

// app/.server/cart.ts
import { createCartServerHandlers, gql } from "@shopify/hydrogen";

const CART_FRAGMENT = gql(`
  fragment CartFragment on Cart {
    appliedGiftCards { id lastCharacters }
    buyerIdentity { countryCode }
    # ... the extra fields your cart UI renders
  }
`);

export const cartHandlers = createCartServerHandlers({ fragment: CART_FRAGMENT });

// app/components/cart/cart-store.ts
import type { CartDataFromHandlers } from "@shopify/hydrogen";
import { createCartComponents } from "@shopify/hydrogen/react";
import type { cartHandlers } from "~/.server/cart";

export type CartData = CartDataFromHandlers<typeof cartHandlers>;

export const { CartProvider, useCart, useCartActions, useCartForm } =
  createCartComponents<typeof cartHandlers>();

// app/root.tsx, inside the Layout <body>
<CartProvider>
  {/* header, main, footer */}
</CartProvider>

<CartForm
  route="/cart"
  action={CartForm.ACTIONS.LinesRemove}
  inputs={{ lineIds: [lineId] }}
>
  <button type="submit">Remove</button>
</CartForm>

function ItemRemoveButton({ lineId }: { lineId: string }) {
  const { formProps, register } = useCartForm();
  return (
    <form {...formProps()}>
      <input type="hidden" {...register("lineId", { value: lineId })} />
      <button type="submit" {...register("remove")}>Remove</button>
    </form>
  );
}

// app/components/product/product-form.tsx
import { createProductComponents } from "@shopify/hydrogen/react";
import type { ProductQuery } from "~/graphql/queries";

export type ProductFormData = NonNullable<ProductQuery["product"]>;

export const { ProductProvider, useProduct, useProductForm } =
  createProductComponents<ProductFormData>();

export default function Product() {
  const { product } = useLoaderData<typeof loader>();
  const selectedVariant = useOptimisticVariant(
    product.selectedOrFirstAvailableVariant,
    getAdjacentAndFirstAvailableVariants(product),
  );
  // ... sync search params with window.history.replaceState
  return (
    <>
      <WeaverseContent />
      <Analytics.ProductView data={{ products: [/* ... */] }} />
    </>
  );
}

import { type ValidProductSelectionResult } from "@shopify/hydrogen";

export default function Product() {
  const { product } = useLoaderData<typeof loader>();
  const navigate = useNavigate();
  const { pathname, search } = useLocation();

  // A selection updates every section at once; the URL follows with a
  // client-side replace. A variant the page already loaded needs no loader run.
  function handleSelect(result: ValidProductSelectionResult<ProductFormData>) {
    const path = productOptionPath(
      product,
      result.selectedOptions,
      result.selectedVariant?.product?.handle, // combined listings link to the other product
      new URLSearchParams(search),
    );
    navigate(localizePath(path, resolveLocale(pathname)), {
      replace: true,
      preventScrollReset: true,
      ...(result.status === "resolved" ? { defaultShouldRevalidate: false } : {}),
    });
  }

  return (
    <ProductProvider product={product} onSelect={handleSelect}>
      <WeaverseContent />
      <ProductAnalytics product={product} />
    </ProductProvider>
  );
}

function OptionPicker() {
  const { options } = useProduct();
  const { register } = useProductForm();
  return options.map((option) => (
    <fieldset key={option.name}>
      <legend>{option.name}</legend>
      {option.values.map((value) => (
        <button
          key={value.name}
          type="button"
          aria-pressed={value.selected}
          disabled={!value.exists}
          onClick={register("optionValue", { optionName: option.name, value: value.name }).onClick}
        >
          {value.name}
        </button>
      ))}
    </fieldset>
  ));
}

function AddToCartButton({ product }: { product: ProductFormData }) {
  const { options, register, formProps, pending } = useProductForm();
  return (
    <form {...formProps({ beforeSubmit: () => openCartDrawer() })}>
      <input type="hidden" {...register("merchandiseId", {})} />
      <input type="hidden" {...register("quantity", { value: 1 })} />
      <button {...register("addToCart", {})} disabled={pending || !canAddToCart(product, options)}>
        Add to cart
      </button>
    </form>
  );
}

<Analytics.Provider cart={cart} shop={data.shop} consent={data.consent}>
  {children}
</Analytics.Provider>

// app/root.tsx, first in <head>
<ShopifyScripts
  nonce={nonce}
  shop={data.shopifyScripts.shop} // { shopId, storefrontId, myshopifyDomain }
  i18n={data.shopifyScripts.i18n} // { country, language, pathPrefix, currency }
  analytics={{ channel: data.shopifyScripts.channel }}
  shopifyAnalytics={data.shopifyScripts.shopifyAnalytics}
  consent={{ mode: data.consent.mode }} // "default-banner" for Shopify's banner
  routes={routeTemplates}
  navigate={navigate}
/>

// app/root.tsx, inside <CartProvider>
<CustomAnalytics />
<PageView />
<CartAnalytics />

// app/routes/account/auth/login.ts
export async function loader({ context }: LoaderFunctionArgs) {
  return context.customerAccount.login();
}

// app/.server/customer-account.ts
import {
  createCustomerAccountClient,
  createCustomerAccountServerHandlers,
  createCustomerSession,
} from "@shopify/hydrogen/customer-account";

const customerSession = createCustomerSession({
  shopId: env.SHOP_ID,
  customerAccountApiClientId: env.PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID,
});

// Registered in handleShopifyRoutes (Step 3)
const handlers = createCustomerAccountServerHandlers({
  customerSession,
  defaultPostLoginRedirectPathname: "/account",
});

const accessToken = await customerSession.getOrRefreshAccessToken(session, requestContext);
const client = createCustomerAccountClient({ shopId: env.SHOP_ID, requestContext });
const { data, errors } = await client.graphql(CUSTOMER_DETAILS_QUERY, { accessToken });

// Before
import { Image, Money, Pagination, getPaginationVariables, getSeoMeta } from "@shopify/hydrogen";

// After
import { Image } from "~/components/image";
import { Money } from "~/components/money";
import { Pagination } from "~/components/pagination";
import { getPaginationVariables } from "~/utils/pagination";
import { getSeoMeta } from "~/utils/seo-meta";

npm run typecheck   # react-router typegen && tsc && hydrogen gql check --fail-on-warn
npm run build
npm run preview     # production build on http://localhost:3456

// app/routes/market-guard.ts — wraps the `:locale?` page routes
export function loader({ request }: LoaderFunctionArgs) {
  if (isUnsupportedMarketPath(new URL(request.url).pathname)) {
    throw new Response("page", { status: 404 });
  }
  return null;
}

// app/routes/market-guard-resources.ts — wraps the `:locale?` resource routes
function guardMarket({ request }: { request: Request }, next: () => Promise<Response>) {
  if (isUnsupportedMarketPath(new URL(request.url).pathname)) {
    throw new Response(null, { status: 404 });
  }
  return next();
}

export const middleware: MiddlewareFunction<Response>[] = [guardMarket];