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 in your app load context:

import { WeaverseClient } from '@weaverse/hydrogen'

export async function createAppLoadContext(
  request: Request,
  env: Env,
  executionContext: ExecutionContext
) {
  const hydrogenContext = createHydrogenContext({
    env,
    request,
    cache,
    waitUntil,
    session,
    i18n: getLocaleFromRequest(request),
    cart: { queryFragment: CART_QUERY_FRAGMENT },
  })

  return {
    ...hydrogenContext,
    weaverse: new WeaverseClient({
      ...hydrogenContext,
      request,
      cache,
      themeSchema,
      components,
      // Optional: override env-based project resolution
      projectId: env.WEAVERSE_PROJECT_ID,
      // Optional: request timeout in milliseconds
      fetchTimeoutMs: 10_000,
    }),
  }
}

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']
  withCache: ReturnType<typeof createWithCache>

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

type WeaverseClientArgs = HydrogenContext & {
  components: HydrogenComponent[]
  themeSchema: HydrogenThemeSchema
  request: Request
  cache: Cache
  projectId?: string | (() => string) | (() => Promise<string>)
  fetchTimeoutMs?: number
}

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 }: ComponentLoaderArgs) {
  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<ThemeSettingsResponse>

The response can contain:

type ThemeSettingsResponse = {
  theme?: HydrogenThemeSettings
  schema?: HydrogenThemeSchema
  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 context.storefront.i18n; 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, 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: HydrogenComponentData
): Promise<HydrogenComponentData>

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

`generateFallbackPage`

generateFallbackPage(message: string): HydrogenPageData

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

Content API

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