Integrating Weaverse into an Existing Hydrogen Project

This guide details how to integrate the Weaverse SDK into your existing Shopify Hydrogen project. By adding Weaverse, you empower your storefront with visual page building, theme customization through the Weaverse Studio, and access to a growing library of components, significantly speeding up development and content management.

Weaverse v5 runs on React Router v7, aligning with Shopify Hydrogen’s React Router migration. See the current Hydrogen updates, then pick the version that matches your Hydrogen setup:

Hydrogen on React Router v7 (2025.5.0 and newer): use @weaverse/hydrogen@5 (latest)
Hydrogen on Remix (older releases): use @weaverse/hydrogen@4 (legacy)

Not sure which you have? Check package.json for react-router vs @remix-run/react.

All code in this guide targets Weaverse v5 + React Router v7 and mirrors the current Pilot theme. Legacy Remix snippets appear only in examples explicitly labelled v4 / Before.

Prerequisites

Before you start, ensure you have:

An existing Shopify Hydrogen project set up and running locally.
Node.js 20+ and npm/yarn/pnpm installed.
Your Hydrogen project connected to your Shopify store.
A Weaverse account and a Weaverse Project created for your storefront.
Basic familiarity with Hydrogen concepts and either:
- React Router v7 (Hydrogen 2025.5.0+) — recommended
- Remix (older Hydrogen versions) — legacy support only

Migration Consideration

If you’re currently on Hydrogen with Remix and want to move to React Router v7, review the current Hydrogen updates first, then install Weaverse v5. See also the Weaverse v5 migration guide. Alternatively, stay on Weaverse v4 with your current Remix setup.

Step 1: Install Weaverse SDK

Navigate to your Hydrogen project directory in your terminal and add the Weaverse Hydrogen SDK.

For Hydrogen with React Router v7 (Recommended)

npm install @weaverse/hydrogen@latest
# or
yarn add @weaverse/hydrogen@latest

For Hydrogen with Remix (Legacy — v4)

npm install @weaverse/hydrogen@4
# or
yarn add @weaverse/hydrogen@4

How to Check Your Hydrogen Version

Check your package.json dependencies:

React Router v7: contains react-router, @react-router/dev, and @shopify/hydrogen@2025.5.0+
Remix: contains @remix-run/react

# Check your Hydrogen version
npm list @shopify/hydrogen

Step 2: Configure Environment Variables

Weaverse needs credentials to connect to your project. Add the following variables to your .env file (create one if it doesn’t exist) at the root of your Hydrogen project:

# .env

# Required
WEAVERSE_PROJECT_ID="your-project-id"

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

# Ensure your existing Shopify variables are also present
# SESSION_SECRET=...
# PUBLIC_STORE_DOMAIN=...
# PUBLIC_STOREFRONT_API_TOKEN=...
# ... other variables

Replace "your-project-id" with the Project ID found in your Weaverse project settings.

Step 3: Set Up Core Weaverse Files

Create a weaverse folder inside your app directory (app/weaverse/). This folder will house Weaverse-specific configurations and utilities.

1. Theme Schema (`~/weaverse/schema.server.ts`)

This file defines your theme’s metadata (name, author, version), global settings schema (which populates the Theme Customizer in Weaverse Studio), and i18n configuration.

// app/weaverse/schema.server.ts
import type { HydrogenThemeSchema } from "@weaverse/hydrogen";
import { COUNTRIES, DEFAULT_LOCALE } from "~/utils/const";
import { version } from "../../package.json";

export const themeSchema: HydrogenThemeSchema = {
  info: {
    version,
    author: "Your Store Name", // Customize
    name: "Your Theme Name", // Customize
    authorProfilePhoto: "", // Optional: URL to author photo
    documentationUrl: "https://docs.weaverse.io",
    supportUrl: "https://help.weaverse.io/",
  },
  // i18n settings (optional but recommended)
  i18n: {
    urlStructure: "url-path",
    defaultLocale: DEFAULT_LOCALE,
    shopLocales: Object.entries(COUNTRIES).map(
      ([pathPrefix, { label, language, country }]) => ({
        pathPrefix: pathPrefix === "default" ? "" : pathPrefix,
        label,
        language,
        country,
      }),
    ),
  },
  // Theme settings shown in Weaverse Studio > Theme > Customize
  settings: [
    {
      group: "Colors",
      inputs: [
        {
          type: "color",
          label: "Primary Button",
          name: "buttonPrimaryBg",
          defaultValue: "#000000",
        },
        // Add more color settings...
      ],
    },
    {
      group: "Layout",
      inputs: [
        {
          type: "range",
          label: "Page width",
          name: "pageWidth",
          configs: { min: 1000, max: 1600, step: 10, unit: "px" },
          defaultValue: 1280,
        },
        // Add more layout settings...
      ],
    },
    // Add more groups like Typography, Header, Footer, etc.
  ],
};

Pilot splits its theme settings into one file per group under app/weaverse/settings/ and composes them in the settings array. It’s a good pattern once the schema grows.

2. Global Styles (`~/weaverse/style.tsx`)

This component applies global CSS variables based on the theme settings defined in schema.server.ts and configured in Weaverse Studio.

// app/weaverse/style.tsx
import { useThemeSettings } from "@weaverse/hydrogen";
import type { ThemeSettings } from "~/types/weaverse";

export function GlobalStyle() {
  const settings = useThemeSettings<ThemeSettings>();
  if (settings) {
    const {
      colorBackground,
      colorText,
      // ... other settings extracted from theme
      pageWidth,
    } = settings;

    return (
      <style
        id="global-theme-style"
        key="global-theme-style"
        suppressHydrationWarning
        dangerouslySetInnerHTML={{
          __html: `
            :root {
              --color-background: ${colorBackground};
              --color-text: ${colorText};
              --page-width: ${pageWidth}px;

              /* Add more CSS variables based on your settings */
            }
          `,
        }}
      />
    );
  }
  return null;
}

3. Component Registration (`~/weaverse/components.ts`)

This is the central file where you register all the React components that you want to be available for use within the Weaverse editor.

// app/weaverse/components.ts
import type { HydrogenComponent } from "@weaverse/hydrogen";
import * as Heading from "~/components/heading";
import * as Link from "~/components/link";
// Import your theme components
import * as FeaturedProducts from "~/sections/featured-products";
import * as HeroImage from "~/sections/hero-image";
// ... other component imports

// Register the components you want to use in Weaverse
export const components: HydrogenComponent[] = [
  Heading,
  Link,
  HeroImage,
  FeaturedProducts,
  // Add all components intended for Weaverse editing...
];

4. WeaverseContent Component (`~/weaverse/index.tsx`)

This component renders Weaverse content using WeaverseHydrogenRoot with your registered components. Export a validateWeaverseData helper here too — routes call it to return a 404 when a page has no published Weaverse content.

// app/weaverse/index.tsx
import {
  WeaverseHydrogenRoot,
  type WeaverseLoaderData,
} from "@weaverse/hydrogen";
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 });
  }
}

5. Content Security Policy (CSP) (`~/weaverse/csp.ts`)

This utility produces the CSP directives required for the Weaverse Studio iframe to work. Note the context type is HydrogenRouterContextProvider from @shopify/hydrogen — not the Remix AppLoadContext.

// app/weaverse/csp.ts
import type { HydrogenRouterContextProvider } from "@shopify/hydrogen";

export function getWeaverseCsp(
  request: Request,
  context: HydrogenRouterContextProvider,
) {
  const url = new URL(request.url);
  // Get weaverse host from query params
  const weaverseHost =
    url.searchParams.get("weaverseHost") || context.env.WEAVERSE_HOST;
  const isDesignMode = url.searchParams.get("weaverseHost");
  const weaverseHosts = ["*.weaverse.io", "*.shopify.com", "*.myshopify.com"];
  if (weaverseHost) {
    weaverseHosts.push(weaverseHost);
  }

  const updatedCsp: { [x: string]: string[] | string | boolean } = {
    defaultSrc: [
      "data:",
      "*.youtube.com",
      "*.youtu.be",
      "*.vimeo.com",
      "*.google.com",
      "*.google-analytics.com",
      "*.googletagmanager.com",
      "cdn.jsdelivr.net",
      ...weaverseHosts,
    ],
    connectSrc: [
      "vimeo.com",
      "*.shopifysvc.com",
      "*.google-analytics.com",
      ...weaverseHosts,
    ],
    styleSrc: weaverseHosts,
    scriptSrc: ["https://cdn.shopify.com"],
  };

  // In design mode, allow the Studio to frame the storefront
  if (isDesignMode) {
    updatedCsp.frameAncestors = ["*"];
  }

  return updatedCsp;
}

Step 4: Add the Weaverse Client to Your Hydrogen Context

A crucial step is to initialize the Weaverse client and attach it to your Hydrogen router context. This makes context.weaverse available in every loader and action.

1. Update Your Context File

In current Hydrogen, the context lives in app/.server/context.ts and exports createHydrogenRouterContext. createHydrogenContext() returns a RouterContextProvider class instance — spreading it into a plain object would destroy the prototype and break Hydrogen. Attach Weaverse with Object.assign and return the original instance:

// app/.server/context.ts
import { createHydrogenContext } from "@shopify/hydrogen";
import { WeaverseClient } from "@weaverse/hydrogen";
import {
  CART_MUTATION_FRAGMENT,
  CART_QUERY_FRAGMENT,
} from "~/graphql/fragments";
import { components } from "~/weaverse/components";
import { themeSchema } from "~/weaverse/schema.server";
// ... your AppSession and getLocaleFromRequest helpers

const additionalContext = {
  // Add custom context values here.
} as const;

type AdditionalContextType = typeof additionalContext;

declare global {
  interface HydrogenAdditionalContext extends AdditionalContextType {}
}

export async function createHydrogenRouterContext(
  request: Request,
  env: Env,
  executionContext: ExecutionContext,
) {
  if (!env?.SESSION_SECRET) {
    throw new Error("SESSION_SECRET environment variable is not set");
  }

  const waitUntil = executionContext.waitUntil.bind(executionContext);
  const [cache, session] = await Promise.all([
    caches.open("hydrogen"),
    AppSession.init(request, [env.SESSION_SECRET]),
  ]);

  const hydrogenContext = createHydrogenContext(
    {
      env,
      request,
      cache,
      waitUntil,
      session,
      i18n: getLocaleFromRequest(request),
      cart: {
        queryFragment: CART_QUERY_FRAGMENT,
        mutateFragment: CART_MUTATION_FRAGMENT,
      },
    },
    additionalContext,
  );

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

  // Add weaverse directly to the hydrogenContext instance.
  // This preserves the RouterContextProvider class instance.
  Object.assign(hydrogenContext, { weaverse });

  return hydrogenContext;
}

Do not write return { ...hydrogenContext, weaverse }. Spreading flattens the RouterContextProvider instance into a plain object and Hydrogen’s context APIs (context.get, middleware) will fail at runtime.

This modification:

Imports WeaverseClient from the Weaverse Hydrogen SDK
Imports your theme schema and components from the files created in the previous step
Initializes a WeaverseClient with the Hydrogen context, request, and cache
Attaches the client to the existing context instance, exposing it as context.weaverse

2. Ensure Your Server Entry Uses the Context

Your server.ts should build the context and hand it to the request handler:

// 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,
  ): Promise<Response> {
    try {
      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;
    } catch (error) {
      console.error(error);
      return new Response("An unexpected error occurred", { status: 500 });
    }
  },
};

The virtual module is still named virtual:react-router/server-build — the remixBuild identifier in Pilot is just a variable name, not a Remix import.

Step 5: Integrate Weaverse into Your Application

Now, let’s modify your existing Hydrogen files to enable Weaverse.

1. Update CSP in `entry.server.tsx`

Spread getWeaverseCsp() into createContentSecurityPolicy(). On React Router v7 the entry renders ServerRouter (not RemixServer) and the context parameter is typed as HydrogenRouterContextProvider:

// app/entry.server.tsx
import {
  createContentSecurityPolicy,
  type HydrogenRouterContextProvider,
} from "@shopify/hydrogen";
import { isbot } from "isbot";
import { renderToReadableStream } from "react-dom/server";
import type { EntryContext } from "react-router";
import { ServerRouter } from "react-router";
import { getWeaverseCsp } from "~/weaverse/csp";

export default async function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  reactRouterContext: EntryContext,
  context: HydrogenRouterContextProvider,
) {
  const { nonce, header, NonceProvider } = createContentSecurityPolicy({
    // Weaverse CSP directives
    ...getWeaverseCsp(request, context),
    // Keep your existing shop CSP config
    shop: {
      checkoutDomain:
        context.env?.PUBLIC_CHECKOUT_DOMAIN || context.env?.PUBLIC_STORE_DOMAIN,
      storeDomain: context.env?.PUBLIC_STORE_DOMAIN,
    },
  });

  const body = await renderToReadableStream(
    <NonceProvider>
      <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 so a partial CSP never breaks the storefront.
  // 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,
  });
}

2. Update the Root Route

Weaverse needs to wrap the component that renders the full HTML document. In current Hydrogen that’s the Layout export — so wrap Layout with withWeaverse and leave the default App export unwrapped:

// app/root.tsx
import { useNonce } from "@shopify/hydrogen";
import { useThemeSettings, withWeaverse } from "@weaverse/hydrogen";
import {
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
  useRouteLoaderData,
} from "react-router";
import type { ThemeSettings } from "~/types/weaverse";
import { DEFAULT_LOCALE } from "~/utils/const";
import { GlobalStyle } from "./weaverse/style";

export type RootLoader = typeof loader;

// The route component — plain, not wrapped
function App() {
  return <Outlet />;
}

// The document layout — wrapped with withWeaverse
export const Layout = withWeaverse(function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  const nonce = useNonce();
  const data = useRouteLoaderData<RootLoader>("root");
  const locale = data?.selectedLocale ?? DEFAULT_LOCALE;
  const { topbarText } = useThemeSettings<ThemeSettings>();

  return (
    <html lang={locale.language}>
      <head>
        {/* ... meta tags, links */}
        <Meta />
        <Links />
        <GlobalStyle /> {/* Include the GlobalStyle component */}
      </head>
      <body>
        {/* ... your header */}
        <main>{children}</main>
        {/* ... your footer */}
        <ScrollRestoration nonce={nonce} />
        <Scripts nonce={nonce} />
      </body>
    </html>
  );
});

export default App;

Wrap Layout, not the default export. Wrapping App with withWeaverse leaves the Weaverse providers below the document boundary, so theme settings and Studio design mode won’t initialize correctly.

Note: withWeaverse doesn’t take a components list. Components are registered in components.ts and consumed by WeaverseContent.

v4 / Before (Remix)

In Weaverse v4 the imports came from @remix-run/react and the default export was wrapped:

// app/root.tsx — v4 (Remix), legacy
import { Outlet } from "@remix-run/react";
import { withWeaverse } from "@weaverse/hydrogen";

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

export default withWeaverse(App);

3. Register Routes in `app/routes.ts`

React Router v7 uses config-based routing. Hydrogen wraps your route tree in hydrogenRoutes(). Add (or confirm) the routes you want Weaverse to drive — Pilot keeps them in feature folders such as routes/home.tsx and routes/products/product.tsx:

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

export default hydrogenRoutes([
  ...prefix(":locale?", [
    index("routes/home.tsx"),
    route("pages/:pageHandle", "routes/pages/regular-page.tsx"),
    route("sitemap-weaverse.xml", "routes/seo/sitemap-weaverse.xml.ts"),
    ...prefix("collections", [
      index("routes/collections/list.tsx"),
      route(":collectionHandle", "routes/collections/collection.tsx"),
    ]),
    ...prefix("products", [
      index("routes/products/list.tsx"),
      route(":productHandle", "routes/products/product.tsx"),
    ]),
    // Catch-all serves Weaverse CUSTOM pages
    route("*", "routes/catch-all.tsx"),
  ]),
]) satisfies RouteConfig;

The route("*", "routes/catch-all.tsx") entry lets Weaverse-authored custom pages resolve at arbitrary handles. Without it, custom pages created in Studio will 404.

4. Adapt Route Components

For each route you want editable in Weaverse:

Load Weaverse page data in the loader with context.weaverse.loadPage()
Validate it with validateWeaverseData()
Render <WeaverseContent />

Homepage (app/routes/home.tsx):

import { AnalyticsPageType } from "@shopify/hydrogen";
import { getWeaverseSeoMeta, type PageType } from "@weaverse/hydrogen";
import type { LoaderFunctionArgs, MetaFunction } from "react-router";
import { validateWeaverseData, WeaverseContent } from "~/weaverse";

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

  if (params.locale && params.locale.toLowerCase() !== locale) {
    // Not a locale — it's probably a custom page handle
    type = "CUSTOM";
  }

  const weaverseData = await context.weaverse.loadPage({ type });
  validateWeaverseData(weaverseData);

  return {
    weaverseData,
    analytics: { pageType: AnalyticsPageType.home },
  };
}

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

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

Product page (app/routes/products/product.tsx):

import { getSelectedProductOptions } from "@weaverse/hydrogen";
import type { LoaderFunctionArgs } from "react-router";
import { PRODUCT_QUERY } from "~/graphql/queries";
import { WeaverseContent } from "~/weaverse";

export async function loader({ params, request, context }: LoaderFunctionArgs) {
  const { productHandle: handle } = params;
  const { storefront, weaverse } = context;
  const selectedOptions = getSelectedProductOptions(request);

  // Load product data and Weaverse page data in parallel
  const [{ shop, product }, weaverseData] = await Promise.all([
    storefront.query(PRODUCT_QUERY, {
      variables: {
        handle,
        selectedOptions,
        country: storefront.i18n.country,
        language: storefront.i18n.language,
      },
    }),
    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 />;
}

v4 / Before (Remix imports in routes)

In Weaverse v4, route types and hooks came from Remix packages:

// v4 (Remix), legacy
import { useLoaderData } from "@remix-run/react";
import type { LoaderFunctionArgs } from "@shopify/remix-oxygen";

In v5, both come from react-router:

// v5 (React Router v7)
import { useLoaderData } from "react-router";
import type { LoaderFunctionArgs } from "react-router";

WeaverseContent automatically renders the content for the page type and handle you loaded, using the components registered in components.ts.

Step 6: Run and Connect

Start your dev server: npm run dev
Open Weaverse Studio: go to your project at studio.weaverse.io.
Update the Preview URL: point your project’s preview URL at your local dev server. Hydrogen’s default is http://localhost:3000; Pilot’s dev script uses --port 3456, so match whatever port your terminal prints.

You should now see your Hydrogen storefront loaded inside the Weaverse editor, ready for visual editing.

Next Steps

Create Custom Components

Build your own React components and make them editable in Weaverse.

Component Schema

Define settings, presets, and child types with createSchema().

Theme Settings

Customize global styles defined in schema.server.ts from Studio.

v5 Migration Guide

Moving an existing Weaverse v4 project to React Router v7.

By following these steps, you can successfully integrate Weaverse into your existing Hydrogen project, unlocking powerful visual editing and customization capabilities.

Overview

Developer Tools

APIs

Hydrogen Themes

Hydrogen Integrations

Migration

Integrating Weaverse into an Existing Hydrogen Project

Prerequisites

Migration Consideration

Step 1: Install Weaverse SDK

For Hydrogen with React Router v7 (Recommended)

For Hydrogen with Remix (Legacy — v4)

How to Check Your Hydrogen Version

Step 2: Configure Environment Variables

Step 3: Set Up Core Weaverse Files

1. Theme Schema (`~/weaverse/schema.server.ts`)

2. Global Styles (`~/weaverse/style.tsx`)

3. Component Registration (`~/weaverse/components.ts`)

4. WeaverseContent Component (`~/weaverse/index.tsx`)

5. Content Security Policy (CSP) (`~/weaverse/csp.ts`)

Step 4: Add the Weaverse Client to Your Hydrogen Context

1. Update Your Context File

2. Ensure Your Server Entry Uses the Context

Step 5: Integrate Weaverse into Your Application

1. Update CSP in `entry.server.tsx`

2. Update the Root Route

3. Register Routes in `app/routes.ts`

4. Adapt Route Components

Step 6: Run and Connect

Next Steps

Create Custom Components

Component Schema

Theme Settings

v5 Migration Guide

​Prerequisites

​Migration Consideration

​Step 1: Install Weaverse SDK

​For Hydrogen with React Router v7 (Recommended)

​For Hydrogen with Remix (Legacy — v4)

​How to Check Your Hydrogen Version

​Step 2: Configure Environment Variables

​Step 3: Set Up Core Weaverse Files

​1. Theme Schema (~/weaverse/schema.server.ts)

​2. Global Styles (~/weaverse/style.tsx)

​3. Component Registration (~/weaverse/components.ts)

​4. WeaverseContent Component (~/weaverse/index.tsx)

​5. Content Security Policy (CSP) (~/weaverse/csp.ts)

​Step 4: Add the Weaverse Client to Your Hydrogen Context

​1. Update Your Context File

​2. Ensure Your Server Entry Uses the Context

​Step 5: Integrate Weaverse into Your Application

​1. Update CSP in entry.server.tsx

​2. Update the Root Route

​3. Register Routes in app/routes.ts

​4. Adapt Route Components

​Step 6: Run and Connect

​Next Steps

Create Custom Components

Component Schema

Theme Settings

v5 Migration Guide

Prerequisites

Migration Consideration

Step 1: Install Weaverse SDK

For Hydrogen with React Router v7 (Recommended)

For Hydrogen with Remix (Legacy — v4)

How to Check Your Hydrogen Version

Step 2: Configure Environment Variables

Step 3: Set Up Core Weaverse Files

1. Theme Schema (`~/weaverse/schema.server.ts`)

2. Global Styles (`~/weaverse/style.tsx`)

3. Component Registration (`~/weaverse/components.ts`)

4. WeaverseContent Component (`~/weaverse/index.tsx`)

5. Content Security Policy (CSP) (`~/weaverse/csp.ts`)

Step 4: Add the Weaverse Client to Your Hydrogen Context

1. Update Your Context File

2. Ensure Your Server Entry Uses the Context

Step 5: Integrate Weaverse into Your Application

1. Update CSP in `entry.server.tsx`

2. Update the Root Route

3. Register Routes in `app/routes.ts`

4. Adapt Route Components

Step 6: Run and Connect

Next Steps