WeaverseClient

WeaverseClient loads Weaverse page data, theme settings, and custom page metadata on the server. It also runs registered component loaders and integrates with Hydrogen caching.

Initialization

Create the client once per request in your app context, from the request’s Hydrogen 2026.10 Storefront API client. Pilot does this in app/.server/context.ts:

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

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({
    storefront,
    env,
    cache,
    waitUntil,
    request,
    customerAccount, // Optional: passed through to section loaders
    themeSchema,
    components,
    // Optional: the market's public locale, when it differs from `storefront.i18n`
    locale: resolveRequestLocale(request),
    // Optional: override env-based project resolution
    projectId: env.WEAVERSE_PROJECT_ID,
    // Optional: request timeout in milliseconds
    fetchTimeoutMs: 10_000,
  })

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

createRequestStorefront, createCustomerAccount, AppSession and resolveRequestLocale are app code; see Step 4 of the v6 migration guide. server.ts copies the returned object onto React Router’s context, so loaders read context.weaverse. See the Project Structure guide for the complete setup.

Public API

class WeaverseClient {
  constructor(args: WeaverseClientArgs)

  API: 'v1'
  basePageConfigs: Omit<WeaverseProjectConfigs, 'requestInfo'>
  basePageRequestBody: Omit<FetchProjectRequestBody, 'url'>
  configs: WeaverseProjectConfigs
  storefront: WeaverseClientArgs['storefront']
  customerAccount: WeaverseClientArgs['customerAccount']
  env: WeaverseClientArgs['env']
  cache: WeaverseClientArgs['cache']
  waitUntil: WeaverseClientArgs['waitUntil']
  request: WeaverseClientArgs['request']
  components: WeaverseClientArgs['components']
  themeSchema: WeaverseClientArgs['themeSchema']

  fetchWithCache<T>(
    url: string,
    options?: WeaverseFetchWithCacheOptions
  ): Promise<T>
  fetchCustomPages(options?: FetchCustomPagesOptions): Promise<CustomPageEntry[]>
  loadThemeSettings(strategy?: CachingStrategy): Promise<WeaverseThemeSettingsResponse>
  loadPage(params?: LoadPageParams): Promise<WeaverseLoaderData | null>
  execComponentLoader(item: WeaverseComponentData): Promise<WeaverseComponentData>
  generateFallbackPage(message: string): WeaversePageData
}

type WeaverseClientArgs = {
  storefront: WeaverseStorefront // Hydrogen 2026.10 Storefront API client
  locale?: WeaverseI18n // defaults to `storefront.i18n`
  env: WeaverseEnv
  waitUntil?: (promise: Promise<unknown>) => void
  customerAccount?: unknown
  components: WeaverseComponent[]
  themeSchema: WeaverseThemeSchema
  request: Request
  cache: Cache
  projectId?: string | (() => string) | (() => Promise<string>)
  fetchTimeoutMs?: number
  throwPageLoadFailures?: boolean
}

locale selects the content locale, the Translation Manager overrides (${language}-${country}, lowercased) and the locale Studio reads, so include pathPrefix. Pass it when the Storefront client’s i18n.language is a Shopify LanguageCode that differs from the market’s public language, such as ZH_TW for a Traditional Chinese Hong Kong market. Added in @weaverse/hydrogen 6.1.0.
throwPageLoadFailures: true makes loadPage() reject with a WeaverseLoadError when the content API is unavailable, instead of resolving to null, so a route can answer an outage differently from a missing page.

API is the current API version segment ('v1'), not a complete endpoint URL.

Methods

`fetchWithCache`

Fetch data through Hydrogen’s cache integration:

fetchWithCache<T>(
  url: string,
  options?: RequestInit & {
    cacheTarget?: BuilderApiCacheTarget
    strategy?: CachingStrategy
  }
): Promise<T>

export async function loader({ weaverse }: WeaverseComponentLoaderArgs) {
  const products = await weaverse.fetchWithCache<Product[]>(
    'https://api.example.com/products',
    {
      strategy: {
        maxAge: 60,
        staleWhileRevalidate: 600,
      },
    }
  )

  return { products }
}

Use strategy, not the Fetch API cache property, for Hydrogen cache-control options.

`loadThemeSettings`

loadThemeSettings(
  strategy?: CachingStrategy
): Promise<WeaverseThemeSettingsResponse>

The response can contain:

type WeaverseThemeSettingsResponse = {
  theme?: WeaverseThemeSettings
  schema?: WeaverseThemeSchema
  publicEnv?: PublicEnv
  staticContent?: Record<string, unknown>
  merchantOverrides?: Record<string, unknown>
  _error?: string
  _loadFailed?: boolean
}

Return the complete response under weaverseTheme from the root loader so withWeaverse can initialize theme and translation stores:

export async function loader({ context }: Route.LoaderArgs) {
  return {
    weaverseTheme: await context.weaverse.loadThemeSettings(),
  }
}

Read settings directly from the response with response.theme.

`loadPage`

loadPage(params?: {
  type?: PageType
  locale?: string
  handle?: string
  strategy?: CachingStrategy
  projectId?: string
}): Promise<WeaverseLoaderData | null>

`type`

Supported PageType values:

'*'
'INDEX'
'PRODUCT'
'ALL_PRODUCTS'
'COLLECTION'
'COLLECTION_LIST'
'PAGE'
'BLOG'
'ARTICLE'
'CUSTOM'

When omitted, the content service resolves the page from the request URL and project configuration.

`locale`

An optional BCP 47 locale override such as en-US, sv-SE, or fr-CA. The value is forwarded unchanged. When omitted, the request uses the client’s locale argument, or storefront.i18n when that isn’t set; loadPage() does not implement its own URL-prefix detection or en-us fallback.

`handle`

The resource or custom-page handle used with page types such as PRODUCT, COLLECTION, PAGE, BLOG, and ARTICLE.

`projectId`

Overrides the client’s resolved project ID for this request. Constructor-level projectId can also be a synchronous or asynchronous function for multi-project storefronts.

`strategy`

A Hydrogen CachingStrategy (create one with Cache from @shopify/hydrogen), for example:

strategy: {
  mode: 'public',
  maxAge: 3600,
  staleWhileRevalidate: 86400,
  sMaxAge: 7200,
  staleIfError: 604800,
}

Example

export async function loader({ context, params }: Route.LoaderArgs) {
  const weaverseData = await context.weaverse.loadPage({
    type: 'PRODUCT',
    handle: params.productHandle,
    locale: 'en-US',
  })

  if (!weaverseData) {
    throw new Response('Weaverse page load failed', { status: 500 })
  }

  return { weaverseData }
}

A missing page payload is normalized into a fallback page. null indicates that loading or validation failed; do not treat it as a reliable page-not-found signal.

`fetchCustomPages`

fetchCustomPages(options?: {
  limit?: number
  locale?: string
}): Promise<CustomPageEntry[]>

Fetches published custom-page entries for sitemap and route-generation workflows.

const pages = await context.weaverse.fetchCustomPages({
  locale: 'en-US',
  limit: 100,
})

`execComponentLoader`

execComponentLoader(
  item: WeaverseComponentData
): Promise<WeaverseComponentData>

Runs the registered loader for one component and attaches its loader data. loadPage() calls this internally.

`generateFallbackPage`

generateFallbackPage(message: string): WeaversePageData

Creates the page structure used when the content response does not include page data.

WeaverseHydrogenRoot - Render loader data
withWeaverse - Initialize root theme and Studio providers
Data Fetching and Caching - Component data loading

Overview

Hooks

Components

Utilities & Types

WeaverseClient

WeaverseClient

Initialization

Public API

Methods

`fetchWithCache`

`loadThemeSettings`

`loadPage`

`type`

`locale`

`handle`

`projectId`

`strategy`

Example

`fetchCustomPages`

`execComponentLoader`

`generateFallbackPage`

​WeaverseClient

​Initialization

​Public API

​Methods

​fetchWithCache

​loadThemeSettings

​loadPage

​type

​locale

​handle

​projectId

​strategy

​Example

​fetchCustomPages

​execComponentLoader

​generateFallbackPage

​Related

WeaverseClient

Initialization

Public API

Methods

`fetchWithCache`

`loadThemeSettings`

`loadPage`

`type`

`locale`

`handle`

`projectId`

`strategy`

Example

`fetchCustomPages`

`execComponentLoader`

`generateFallbackPage`

Related