Skip to main content

​
WeaverseClient

The WeaverseClient class is a server-side utility that provides methods to interact with Weaverse services, fetch content, manage caching strategies, and load theme settings and page data for your Hydrogen storefront.

​
Initialization

The WeaverseClient is typically initialized in your server.ts file and injected into your app’s load context: 
// Example from templates/pilot/server.ts
export async function createAppLoadContext(
  request: Request,
  env: Env,
  executionContext: ExecutionContext,
) {
  // ... other context setup

  let 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,
    }),
  };
}
Refer to the Project Structure guide for a detailed setup walkthrough.

​
Type Definition

class WeaverseClient {
  constructor(args: WeaverseClientArgs);
  
  // Properties
  public API: string;  // API endpoint path
  public basePageConfigs: Omit<WeaverseProjectConfigs, 'requestInfo'>
  public basePageRequestBody: Omit<FetchProjectRequestBody, 'url'>
  public configs: WeaverseProjectConfigs
  public storefront: HydrogenContext['storefront'];
  public env: HydrogenEnv;
  public cache: Cache;
  public waitUntil: ExecutionContext['waitUntil'];
  public request: Request;
  public components: HydrogenComponent[];
  public themeSchema: HydrogenThemeSchema;
  
  // Methods
  fetchWithCache<T>(url: string, options?: RequestInit & { strategy?: AllCacheOptions }): Promise<T>;
  loadThemeSettings(strategy?: AllCacheOptions): Promise<HydrogenThemeSettings>;
  loadPage(params?: { type?: PageType, locale?: string, handle?: string, strategy?: AllCacheOptions }): Promise<WeaverseLoaderData | null>;
  execComponentLoader(item: HydrogenComponentData): Promise<HydrogenComponentData>;
  generateFallbackPage(message: string): HydrogenPageData;
}

type WeaverseClientArgs = HydrogenContext & {
  components: HydrogenComponent[];
  themeSchema: HydrogenThemeSchema;
  request: Request;
  cache: Cache;
};

​
Methods

​
fetchWithCache

Fetches data from an external API with configurable caching strategies. 
fetchWithCache<T>(url: string, options?: RequestInit & { strategy?: AllCacheOptions }): Promise<T>
Parameters:
  • url: string - The endpoint URL
  • options?: RequestInit & { strategy?: AllCacheOptions } - Cache and fetch configuration
    • strategy - Caching strategy with options like maxAge, staleWhileRevalidate, etc.
    • Other standard fetch options (headers, method, etc.)
Returns:
  • Promise<T> - A promise that resolves with the fetched data
Example: 
// In a component loader
export async function loader({ data, weaverse }: ComponentLoaderArgs) {
  const apiUrl = 'https://api.example.com/products';
  
  const products = await weaverse.fetchWithCache(apiUrl, {
    headers: {
      'Authorization': `Bearer ${process.env.API_KEY}`
    },
    cache: {
      maxAge: 60, // Cache for 60 seconds
      staleWhileRevalidate: 600 // Allow stale content for 10 minutes while revalidating
    }
  });
  
  return { products };
}
Refer to the Data Fetching and Caching guide for more details.

​
loadThemeSettings

Loads the global theme settings for the current Weaverse project. 
loadThemeSettings(strategy?: AllCacheOptions): Promise<HydrogenThemeSettings>
Parameters:
  • strategy?: AllCacheOptions - Optional caching strategy for the theme settings request
Returns:
  • Promise<HydrogenThemeSettings> - The theme settings object
Example: 
// In a route loader
export async function loader({ context }: LoaderFunctionArgs) {
  const { weaverse } = context;
  const themeSettings = await weaverse.loadThemeSettings();
  
  return json({
    themeSettings,
    // other data
  });
}

​
loadPage

Loads a page’s data from Weaverse, including running component loaders. 
loadPage(params?: {
  type?: PageType,
  locale?: string,
  handle?: string,
  strategy?: AllCacheOptions
}): Promise<WeaverseLoaderData | null>
Parameters:
  • params - Object containing:
    • type?: PageType - Type of page (‘INDEX’, ‘PRODUCT’, etc.)
    • locale?: string - Locale for the page
    • handle?: string - Handle/slug for the page
    • strategy?: AllCacheOptions - Caching strategy
Returns:
  • Promise<WeaverseLoaderData | null> - Page data object or null if not found
Example: 
// In a route loader
export async function loader({ context, request, params }: LoaderFunctionArgs) {
  const { weaverse } = context;
  
  const pageData = await weaverse.loadPage({
    type: 'PRODUCT',
    handle: params.handle,
    strategy: {
      maxAge: 60,
      staleWhileRevalidate: 600
    }
  });
  
  if (!pageData) {
    throw new Response('Page not found', { status: 404 });
  }
  
  return json({
    weaverseData: pageData,
    // other data
  });
}

​
execComponentLoader

Executes a component’s loader function to fetch its data. 
execComponentLoader(item: HydrogenComponentData): Promise<HydrogenComponentData>
Parameters:
  • item: HydrogenComponentData - Component data object
Returns:
  • Promise<HydrogenComponentData> - Component data with loader data added
Note: This method is primarily used internally by loadPage to process component loaders.

​
generateFallbackPage

Generates a fallback page when the requested page data isn’t available. 
generateFallbackPage(message: string): HydrogenPageData
Parameters:
  • message: string - Message to display on the fallback page
Returns:
  • HydrogenPageData - A basic page data object with the message
⌘I