Rendering Weaverse Pages

This guide covers everything you need to know about rendering different page types in Weaverse, from basic concepts to advanced implementation patterns.

Core Concepts

Weaverse page rendering revolves around two key elements:

loadPage() function: Loads page data based on type and handle
WeaverseContent component: Renders the loaded page content

The loadPage() Function

The loadPage() function is called in your route loaders to fetch page data:

// In your route loader
export async function loader({ params, context }: LoaderFunctionArgs) {
  const { handle } = params;
  const { weaverse } = context;
  
  const weaverseData = await weaverse.loadPage({
    type: "PRODUCT",     // Page type - determines content structure
    handle: handle,      // Page handle - identifies specific page
  });
  
  return { weaverseData };
}

The WeaverseContent Component

The WeaverseContent component renders the loaded page data. It automatically gets the weaverseData from your loader through the <WeaverseHydrogenRoot> wrapper:

import { WeaverseContent } from "~/weaverse";

export default function ProductPage() {
  // No need to pass weaverseData explicitly - WeaverseHydrogenRoot handles it
  return <WeaverseContent />;
}

How it works: The <WeaverseHydrogenRoot> component (typically in your root layout) automatically extracts weaverseData from the current route’s loader data and provides it to all child <WeaverseContent> components through React context. This eliminates the need to manually pass the data prop.

Supported Page Types

Weaverse supports the following page types:

E-commerce Pages

PRODUCT - Individual product pages
COLLECTION - Collection/category listing pages

Content Pages

PAGE - Shopify Page resources (the pages you manage in Shopify admin), loaded with the page’s handle
BLOG - Blog listing pages
ARTICLE - Individual blog post pages

Special Pages

INDEX - Homepage
CUSTOM - Weaverse custom pages created in Weaverse Studio; resolved from the request URL, so no handle is passed

PAGE and CUSTOM are easy to confuse. Use CUSTOM for pages you built in Weaverse Studio — Pilot serves these from app/routes/catch-all.tsx and resolves the handle from the request URL. Use PAGE with a handle only for Shopify Page resources, the way Pilot’s app/routes/pages/regular-page.tsx serves /pages/:pageHandle.

Pilot uses React Router 7’s manual route registry in app/routes.ts. Creating a file under app/routes/ does not create a route — the module has to be registered with route()/index() before any URL reaches it. Route module code imports LoaderFunctionArgs, MetaFunction, and useLoaderData from react-router, and loaders return plain objects rather than json().

Working with Locales

Localization is request context, not a decision repeated in every page loader. Resolve the active market once from an exact configured allowlist, then use that entry to create both the Shopify Storefront and Weaverse contexts. Normal storefront loaders can then load the active localized page without parsing the URL or hardcoding a fallback:

export async function loader({ params, context }: LoaderFunctionArgs) {
  const weaverseData = await context.weaverse.loadPage({
    type: "PRODUCT",
    handle: params.productHandle,
  });

  return { weaverseData };
}

Do not accept any leading segment merely because it has a locale shape, and do not fall back unconditionally to en-us. A configured prefix selects its exact market; an unsupported exact xx-yy prefix returns 404; an ordinary slug remains routable.

Locale switches must preserve valid paths and queries and perform a document navigation so the next request rebuilds Shopify and Weaverse data. Links, redirects, cart actions, checkout, and React Router .data requests must retain the same active market. Use an explicit locale only for an intentional cross-locale admin or background operation, not as a second storefront routing system.

Advanced Localization Guide

Implement the exact routing, context, continuity, SEO, and translation contract.

Markets and Localization

Define the canonical market table and configure localized content.

Routes Without Weaverse Integration

Some routes in your Hydrogen theme may not use Weaverse’s page system at all. These typically include functional pages that rely heavily on Shopify’s built-in components and APIs:

Search pages - Use Shopify’s search API directly
Cart pages - Use Shopify’s cart components and forms
Account pages - Use Shopify’s customer account API
Policy pages - Often render Shopify’s policy content directly

Custom Page Approach

Use the page type that matches the resource being rendered:

Shopify Page Resources: PAGE Type with Handle

Use PAGE only for a Shopify Page resource, normally under /pages/:pageHandle:

// app/routes/pages/regular-page.tsx
export async function loader({ params, context }: LoaderFunctionArgs) {
  const { weaverse } = context;
  const { pageHandle } = params;
  
  const weaverseData = await weaverse.loadPage({
    type: "PAGE",
    handle: pageHandle,
  });
  
  return { weaverseData };
}

Weaverse Custom Pages: CUSTOM Type

For a root-level custom page created in Studio, let Weaverse resolve the page from the current request URL:

// Example: Dynamic custom page routing
export async function loader({ params, context }: LoaderFunctionArgs) {
  const { weaverse } = context;
  
  const weaverseData = await weaverse.loadPage({
    type: "CUSTOM", // No handle needed - URL determines content
  });
  
  return { weaverseData };
}

This approach allows you to create visually customizable pages using Weaverse’s editor while maintaining functional pages that use Shopify’s native components.

Real-World Example: Pilot Template Pattern

Pilot registers application and custom-page routes under an optional first segment, but that route parameter is not the market authority:

// app/routes.ts (excerpt)
...prefix(":locale?", [
  index("routes/home.tsx"),
  // …all concrete routes…
  route("*", "routes/catch-all.tsx"),
]),

Before React Router handles the request, the server rejects an exact locale-shaped prefix that is not in the canonical market table:

if (isUnsupportedMarketPath(new URL(request.url).pathname)) {
  return new Response("Not Found", { status: 404 });
}

return handleRequest(request);

This boundary makes the optional route safe:

A configured prefix selects its exact Shopify and Weaverse market context.
An invented prefix such as /en-xx returns 404 before any route can serve default-market content there.
Ordinary root-level handles such as /about-us or /hi-india continue to the Weaverse custom-page path.
The catch-all loads custom pages with loadPage({type: "CUSTOM"}); it does not reinterpret arbitrary text as a locale.

Keep this request boundary and the canonical market table together. A regex alone can identify locale-shaped text, but only the allowlist can authorize a market route.

// Search page without Weaverse (from Pilot template)
// app/routes/search/index.tsx — registered as route("search", "routes/search/index.tsx")
export default function Search() {
  const { searchTerm, products } = useLoaderData<typeof loader>();
  
  // No WeaverseContent component - uses native Shopify search functionality
  return (
    <Section width="fixed" verticalPadding="medium">
      <Form method="get">
        <input name="q" placeholder="Search our store..." />
      </Form>
      <Pagination connection={products}>
        {/* Native Shopify components */}
      </Pagination>
    </Section>
  );
}

// Account page without Weaverse (from Pilot template)
// app/routes/account/dashboard/index.tsx — registered under the `account` prefix
export default function Account() {
  const { customer } = useLoaderData<typeof loader>();
  
  // No WeaverseContent - uses Shopify's customer account components
  return (
    <Section>
      <AccountDetails customer={customer} />
      <AccountOrderHistory orders={orders} />
      <AccountAddressBook addresses={addresses} />
    </Section>
  );
}

Basic Implementation

Here’s the standard pattern for implementing Weaverse page rendering in a React Router v7 route:

1. Route Loader

// app/routes/products/product.tsx
// Registered in app/routes.ts — see the note in Supported Page Types above.
import type { LoaderFunctionArgs } from "react-router";
import { validateWeaverseData } from "~/weaverse";

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

  // Load both Shopify data and Weaverse page data in parallel
  const [productData, weaverseData] = await Promise.all([
    storefront.query(PRODUCT_QUERY, {
      variables: { handle: productHandle }
    }),
    weaverse.loadPage({
      type: "PRODUCT",
      handle: productHandle,
    }),
  ]);

  if (!productData.product) {
    throw new Response("Product not found", { status: 404 });
  }

  // `loadPage()` returns `WeaverseLoaderData | null` — it resolves to `null`
  // on failure instead of throwing, so check the result explicitly.
  validateWeaverseData(weaverseData);

  // Return a plain object. Reach for `data()` from `react-router` only when
  // you need to attach custom status codes or headers to the response.
  return {
    product: productData.product,
    weaverseData,
  };
}

2. Route Component

import { useLoaderData } from "react-router";
import { WeaverseContent } from "~/weaverse";

export default function ProductPage() {
  // WeaverseHydrogenRoot automatically provides weaverseData to WeaverseContent
  return <WeaverseContent />;
}

Page Type Examples

Product Page

// app/routes/products/product.tsx
// Registered in app/routes.ts as route(":productHandle", "routes/products/product.tsx")
export async function loader({ params, context }: LoaderFunctionArgs) {
  const { productHandle } = params;
  const { storefront, weaverse } = context;
  
  const [{ product }, weaverseData] = await Promise.all([
    storefront.query(PRODUCT_QUERY, {
      variables: { handle: productHandle }
    }),
    weaverse.loadPage({
      type: "PRODUCT",
      handle: productHandle,
    }),
  ]);
  
  return { product, weaverseData };
}

Collection Page

// app/routes/collections/collection.tsx
// Registered in app/routes.ts as route(":collectionHandle", "routes/collections/collection.tsx")
export async function loader({ params, context }: LoaderFunctionArgs) {
  const { collectionHandle } = params;
  const { storefront, weaverse } = context;
  
  const [{ collection }, weaverseData] = await Promise.all([
    storefront.query(COLLECTION_QUERY, {
      variables: { handle: collectionHandle }
    }),
    weaverse.loadPage({
      type: "COLLECTION",
      handle: collectionHandle,
    }),
  ]);
  
  return { collection, weaverseData };
}

Custom Page

// app/routes/pages/regular-page.tsx
// Registered in app/routes.ts as route("pages/:pageHandle", "routes/pages/regular-page.tsx")
export async function loader({ params, context }: LoaderFunctionArgs) {
  const { pageHandle } = params;
  const { storefront, weaverse } = context;
  
  const [{ page }, weaverseData] = await Promise.all([
    storefront.query(PAGE_QUERY, {
      variables: { handle: pageHandle }
    }),
    weaverse.loadPage({
      type: "PAGE",
      handle: pageHandle,
    }),
  ]);
  
  return { page, weaverseData };
}

Blog Page

// app/routes/blogs/blog.tsx
// Registered in app/routes.ts as route(":blogHandle", "routes/blogs/blog.tsx")
export async function loader({ params, context }: LoaderFunctionArgs) {
  const { blogHandle } = params;
  const { storefront, weaverse } = context;
  
  const [{ blog }, weaverseData] = await Promise.all([
    storefront.query(BLOG_QUERY, {
      variables: { handle: blogHandle }
    }),
    weaverse.loadPage({
      type: "BLOG",
      handle: blogHandle,
    }),
  ]);
  
  return { blog, weaverseData };
}

Homepage

// app/routes/home.tsx — registered as index("routes/home.tsx")
export async function loader({ params, context }: LoaderFunctionArgs) {
  const { storefront, weaverse } = context;
  const { pathPrefix } = context.storefront.i18n;
  const locale = pathPrefix?.slice(1) || "";
  
  let type: PageType = "INDEX";
  
  // Handle locale-based routing and custom pages
  if (params.locale && params.locale.toLowerCase() !== locale) {
    // If it's not a locale, it's probably a custom page handle
    type = "CUSTOM";
  }
  
  const [{ shop }, weaverseData] = await Promise.all([
    storefront.query(SHOP_QUERY),
    weaverse.loadPage({ type }),
  ]);
  
  return { shop, weaverseData };
}

Custom Pages

Custom pages are built in Weaverse Studio and are rendered with the CUSTOM type. Weaverse resolves which custom page to serve from the request URL, so you do not pass a handle.

Root-Level Custom Pages Need No New Route

Pilot’s catch-all already covers every unmatched URL, so a custom page published at /about is served without touching app/routes.ts:

// app/routes/catch-all.tsx — registered as route("*", "routes/catch-all.tsx")
export async function loader({ context }: LoaderFunctionArgs) {
  const weaverseData = await context.weaverse.loadPage({
    type: "CUSTOM", // handle comes from the request URL
  });

  validateWeaverseData(weaverseData);

  return { weaverseData };
}

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

Add a dedicated route only when you want a different URL shape (for example nesting campaigns under /promo/...) — and load it with type: "CUSTOM" too. Remember to register it in app/routes.ts:

// app/routes.ts
route("promo/:campaignHandle", "routes/promo/campaign.tsx"),

Shopify Pages (`PAGE` + handle)

PAGE is for Shopify Page resources, not for Weaverse custom pages. Pilot serves these at /pages/:pageHandle:

// app/routes/pages/regular-page.tsx
// Registered as route("pages/:pageHandle", "routes/pages/regular-page.tsx")
export async function loader({ params, context }: LoaderFunctionArgs) {
  const { pageHandle } = params;
  const { storefront, weaverse } = context;

  // Load both Shopify page data and Weaverse page data in parallel
  const [{ page }, weaverseData] = await Promise.all([
    storefront.query(PAGE_QUERY, {
      variables: { handle: pageHandle }
    }),
    weaverse.loadPage({
      type: "PAGE",
      handle: pageHandle,
    }),
  ]);
  
  // Handle page not found (neither Shopify nor Weaverse page exists)
  if (!page && !weaverseData) {
    throw new Response("Page not found", { status: 404 });
  }
  
  return { page, weaverseData };
}

Error Handling

404 Error Handling

Always check if the page data exists and handle 404 cases:

export async function loader({ params, context }: LoaderFunctionArgs) {
  const { handle } = params;
  const { weaverse } = context;
  
  const weaverseData = await weaverse.loadPage({
    type: "PRODUCT",
    handle,
  });
  
  // Check if Weaverse page exists
  if (!weaverseData) {
    throw new Response("Page not found", { status: 404 });
  }
  
  return { weaverseData };
}

Fallback Rendering

Provide fallback content when Weaverse data is unavailable:

export default function ProductPage() {
  const { product, weaverseData } = useLoaderData<typeof loader>();
  
  return (
    <div>
      {weaverseData ? (
        <WeaverseContent />
      ) : (
        <div>
          {/* Fallback content when Weaverse page doesn't exist */}
          <h1>{product.title}</h1>
          <p>{product.description}</p>
        </div>
      )}
    </div>
  );
}

Error Boundaries

Use error boundaries for graceful error handling:

import { ErrorBoundary } from "~/components/ErrorBoundary";

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

Performance Best Practices

Parallel Data Loading

Always load Weaverse data in parallel with other API calls:

// ✅ Good: Parallel loading
const [shopifyData, weaverseData, reviewsData] = await Promise.all([
  storefront.query(PRODUCT_QUERY, { variables }),
  weaverse.loadPage({ type: "PRODUCT", handle }),
  getProductReviews(handle),
]);

// ❌ Bad: Sequential loading
const shopifyData = await storefront.query(PRODUCT_QUERY, { variables });
const weaverseData = await weaverse.loadPage({ type: "PRODUCT", handle });
const reviewsData = await getProductReviews(handle);

Caching

Use proper cache headers for Weaverse pages:

import { routeHeaders } from "~/utils/cache";

export const headers = routeHeaders;

export async function loader({ context }: LoaderFunctionArgs) {
  // Your loader implementation
}

Preloading

Consider preloading critical page data:

// Preload homepage data
export function preload({ context }: LoaderFunctionArgs) {
  return context.weaverse.loadPage({ type: "INDEX" });
}

Troubleshooting

Common Issues

1. Page Type Mismatch

Problem: Wrong page type specified in loadPage()

// ❌ Wrong: Using PRODUCT type for a collection page
weaverse.loadPage({ type: "PRODUCT", handle: collectionHandle })

Solution: Use the correct supported page type

// ✅ Correct: Using COLLECTION type for a collection page
weaverse.loadPage({ type: "COLLECTION", handle: collectionHandle })

Problem: Using unsupported page types

// ❌ Wrong: These page types are not supported
weaverse.loadPage({ type: "SEARCH", handle: "search" })
weaverse.loadPage({ type: "CART", handle: "cart" })
weaverse.loadPage({ type: "ACCOUNT", handle: "account" })

Solution: Many functional pages don’t need Weaverse integration - use native Shopify components instead

// ✅ Correct: Search, cart, and account pages often don't use Weaverse at all
// These routes use Shopify's native components directly:

// Search page - uses Shopify's search API and components
export default function SearchPage() {
  // Uses native Shopify search components, no WeaverseContent needed
}

// Cart page - uses Shopify's cart components and forms  
export default function CartPage() {
  // Uses native Shopify cart components, no WeaverseContent needed
}

// Account page - uses Shopify's customer account components
export default function AccountPage() {
  // Uses native Shopify account components, no WeaverseContent needed
}

Alternative: If you intentionally want a functional route to render a Weaverse custom page instead, create that page in Studio at the same URL and load it as CUSTOM from the route.

// The current request URL determines which Studio custom page is loaded.
const weaverseData = await weaverse.loadPage({ type: "CUSTOM" })

2. Missing Handle Parameter

Problem: Handle not provided or undefined

// ❌ Wrong: Handle is undefined
weaverse.loadPage({ type: "PRODUCT", handle: undefined })

Solution: Always validate handle exists

// ✅ Correct: Validate handle before using
invariant(handle, "Missing product handle");
weaverse.loadPage({ type: "PRODUCT", handle })

3. Component Not Rendering

Problem: Weaverse components not registered properly Solution: Ensure components are registered in ~/weaverse/components.ts (or ~/app/weaverse/components.ts in Pilot template):

import type { HydrogenComponent } from "@weaverse/hydrogen";
import * as ProductInfo from "~/sections/product-info";
import * as Hero from "~/sections/hero";

export const components: HydrogenComponent[] = [
  ProductInfo,
  Hero,
  // Add all your components here
];

Important: Always use namespace imports (* as ComponentName) and restart your dev server after registration.

4. TypeScript Errors

Problem: Type errors with WeaverseContent Solution: Ensure proper type imports:

import type { WeaverseLoaderData } from "@weaverse/hydrogen";

export async function loader({ context }: LoaderFunctionArgs) {
  const weaverseData: WeaverseLoaderData = await context.weaverse.loadPage({
    type: "PRODUCT",
    handle,
  });
  
  return { weaverseData };
}

Next Steps

Learn about Custom Component Development
Explore Data Fetching Patterns
Master Component Schemas
Review API Reference

For more advanced use cases, see the Migration Guide and Custom Routing documentation.

​Rendering Weaverse Pages

​Core Concepts

​The loadPage() Function

​The WeaverseContent Component

​Supported Page Types

​E-commerce Pages

​Content Pages

​Special Pages

​Working with Locales

Advanced Localization Guide

Markets and Localization

​Routes Without Weaverse Integration

​Custom Page Approach

​Shopify Page Resources: PAGE Type with Handle

​Weaverse Custom Pages: CUSTOM Type

​Real-World Example: Pilot Template Pattern

​Basic Implementation

​1. Route Loader

​2. Route Component

​Page Type Examples

​Product Page

​Collection Page

​Custom Page

​Blog Page

​Homepage

​Custom Pages

​Root-Level Custom Pages Need No New Route

​Shopify Pages (PAGE + handle)

​Error Handling

​404 Error Handling

​Fallback Rendering

​Error Boundaries

​Performance Best Practices

​Parallel Data Loading

​Caching

​Preloading

​Troubleshooting

​Common Issues

​1. Page Type Mismatch

​2. Missing Handle Parameter

​3. Component Not Rendering

​4. TypeScript Errors

​Next Steps

Rendering Weaverse Pages

Core Concepts

The loadPage() Function

The WeaverseContent Component

Supported Page Types

E-commerce Pages

Content Pages

Special Pages

Working with Locales

Routes Without Weaverse Integration

Custom Page Approach

Shopify Page Resources: PAGE Type with Handle

Weaverse Custom Pages: CUSTOM Type

Real-World Example: Pilot Template Pattern

Basic Implementation

1. Route Loader

2. Route Component

Page Type Examples

Product Page

Collection Page

Custom Page

Blog Page

Homepage

Custom Pages

Root-Level Custom Pages Need No New Route

Shopify Pages (`PAGE` + handle)

Error Handling

404 Error Handling

Fallback Rendering

Error Boundaries

Performance Best Practices

Parallel Data Loading

Caching

Preloading

Troubleshooting

Common Issues

1. Page Type Mismatch

2. Missing Handle Parameter

3. Component Not Rendering

4. TypeScript Errors

Next Steps