Logo
  1. Docs
  2. API References

Types

Published on Apr 24, 2025, updated 2 months ago

Types

This document outlines the key TypeScript interfaces and types used in the Weaverse Hydrogen package. Understanding these types is essential for building type-safe components and integrating with the Weaverse system.

Component Types

HydrogenComponent

Defines a component module that can be registered with Weaverse.

interface HydrogenComponent<T extends HydrogenComponentProps = any> {  default: ForwardRefExoticComponent<T>;  schema: HydrogenComponentSchema;  loader?: (args: ComponentLoaderArgs) => Promise<unknown>;}

HydrogenComponentProps

Base props for any Weaverse Hydrogen component.

interface HydrogenComponentProps<L = any> extends WeaverseElement {  className?: string;  loaderData?: L;  children?: React.JSX.Element[];}

HydrogenComponentSchema (Legacy)

⚠️ Deprecated: Use the createSchema() function instead of manually defining schema types. See the Component Schema section above for the modern approach.

For legacy reference, the manual schema interface was:

// Legacy approach - use createSchema() insteadinterface HydrogenComponentSchema {  childTypes?: string[];  settings: InspectorGroup[];  inspector?: InspectorGroup[]; // Deprecated: use 'settings' instead  presets?: Omit<HydrogenComponentPresets, 'type'>;  limit?: number;  enabledOn?: {    pages?: ('*' | PageType)[];    groups?: ('*' | 'header' | 'footer' | 'body')[];  };  pages?: ('*' | PageType)[];  groups?: ('*' | 'header' | 'footer' | 'body')[];}

Migration: Replace manual schema definitions with createSchema():

// Old approachexport const schema: HydrogenComponentSchema = { /* ... */ };
// New approachexport let schema = createSchema({ /* ... */ });

HydrogenComponentData

Data structure for a component instance.

interface HydrogenComponentData {  data?: { [key: string]: any };  children?: { id: string }[];  id: string;  createdAt?: string;  updatedAt?: string;  deletedAt?: string;}

Inspector Types

Types used for defining the settings UI in Weaverse Studio.

Note: These types are still called "Inspector" types for historical reasons, but they are used to define the settings property in component schemas. The inspector property itself has been deprecated in favor of settings.

InspectorGroup

interface InspectorGroup {  group: string;  inputs: (BasicInput | HeadingInput)[];}

BasicInput

type BasicInput = Omit<CoreBasicInput, 'condition'> & {  shouldRevalidate?: boolean;  condition?:    | string    | ((data: ElementData, weaverse: WeaverseHydrogen) => boolean);};

HeadingInput

type HeadingInput = {  type: 'heading';  label: string;  [key: string]: any;};

Loader Types

Types related to data loading and server integration.

ComponentLoaderArgs

type ComponentLoaderArgs<T = any, E = any> = {  data: T;  weaverse: WeaverseClient;};

RouteLoaderArgs

interface RouteLoaderArgs extends RemixOxygenLoaderArgs {  context: AppLoadContext & {    weaverse: WeaverseClient;  };}

WeaverseLoaderData

interface WeaverseLoaderData {  configs: Omit<WeaverseProjectConfigs, 'publicEnv'> & {    requestInfo: WeaverseLoaderRequestInfo;  };  page: HydrogenPageData;  project: HydrogenProjectType;  pageAssignment: HydrogenPageAssignment;}

Theme Types

HydrogenThemeSettings

type HydrogenThemeSettings = {  [key: string]: any;};

HydrogenThemeSchema

interface HydrogenThemeSchema {  info: {    name: string;    version: string;    author: string;    authorProfilePhoto: string;    documentationUrl: string;    supportUrl: string;  };  settings: InspectorGroup[];  inspector?: InspectorGroup[]; // Deprecated: use 'settings' instead  i18n?: {    urlStructure: 'url-path' | 'subdomain' | 'top-level-domain';    defaultLocale: WeaverseI18n;    shopLocales: WeaverseI18n[];  };}

Note: The inspector property has been deprecated in favor of settings. While inspector is still supported for backward compatibility, new theme schemas should use settings.

Miscellaneous Types

PageType

Enumerates supported page types in Shopify Hydrogen.

type PageType =  | 'INDEX'  | 'PRODUCT'  | 'ALL_PRODUCTS'  | 'COLLECTION'  | 'COLLECTION_LIST'  | 'PAGE'  | 'BLOG'  | 'ARTICLE'  | 'CUSTOM';

WeaverseI18n

Internationalization configuration.

type WeaverseI18n = I18nBase & {  label?: string;  pathPrefix?: string;  [key: string]: any;};

Usage Example

Here's how you might use these types to define a component:

import type {  HydrogenComponent,  HydrogenComponentProps,} from '@weaverse/hydrogen';import { createSchema } from '@weaverse/hydrogen';
type HeroBannerProps = HydrogenComponentProps<{  featuredProducts: any[];}> & {  heading: string;  subheading?: string;  backgroundImage?: string;  textColor?: string;};
function HeroBanner({  heading,  subheading,  backgroundImage,  textColor = '#ffffff',  loaderData,}: HeroBannerProps) {  const { featuredProducts } = loaderData || {};    return (    <div       className="hero-banner"       style={{         backgroundImage: `url(${backgroundImage})`,        color: textColor,      }}    >      <h1>{heading}</h1>      {subheading && <p>{subheading}</p>}            {featuredProducts?.length > 0 && (        <div className="featured-products">          {featuredProducts.map(product => (            <div key={product.id}>{product.title}</div>          ))}        </div>      )}    </div>  );}
let schema = createSchema({  type: 'hero-banner',  title: 'Hero Banner',  settings: [    {      group: 'Content',      inputs: [        {          type: 'text',          name: 'heading',          label: 'Heading',          defaultValue: 'Welcome to our store',        },        {          type: 'text',          name: 'subheading',          label: 'Subheading',        },      ],    },    {      group: 'Styling',      inputs: [        {          type: 'image',          name: 'backgroundImage',          label: 'Background Image',        },        {          type: 'color',          name: 'textColor',          label: 'Text Color',          defaultValue: '#ffffff',        },      ],    },  ],});
async function loader({ data, weaverse }) {  // Fetch featured products  const products = await weaverse.storefront.query('FEATURED_PRODUCTS_QUERY');    return {    featuredProducts: products?.data?.products?.nodes || [],  };}
HeroBanner.defaultProps = {  heading: 'Welcome to our store',};
export default HeroBanner;export { schema, loader };

Type Extensions

Weaverse Hydrogen extends several types from Remix Oxygen and Shopify Hydrogen:

// Extend AppLoadContext with the weaverse clientdeclare module '@shopify/remix-oxygen' {  export interface AppLoadContext {    weaverse: WeaverseClient;  }}
// Extend HydrogenEnv with Weaverse environment variablesdeclare module '@shopify/hydrogen' {  interface HydrogenEnv {    WEAVERSE_PROJECT_ID: string;    WEAVERSE_HOST: string;    WEAVERSE_API_KEY: string;  }}

Related

Component Schema

The modern way to define component schemas is using the createSchema() function:

import { createSchema } from '@weaverse/hydrogen';
export let schema = createSchema({  type: 'my-component',  title: 'My Component',  settings: [    // ... settings configuration  ],});

The createSchema() function provides:

  • Runtime validation using Zod
  • Better TypeScript inference
  • Consistent validation across all schemas
  • Future-proof schema definitions

Schema Properties

When using createSchema(), you can define the following properties:

export let schema = createSchema({  title: string;                    // Display name in Weaverse Studio  type: string;                     // Unique component identifier  settings?: InspectorGroup[];      // UI controls configuration  childTypes?: string[];            // Allowed child component types  limit?: number;                   // Maximum instances allowed  enabledOn?: {                     // Where component can be used    pages?: PageType[];    groups?: ('*' | 'header' | 'footer' | 'body')[];  };  presets?: {                       // Default values and children    children?: ComponentPresets[];    [key: string]: any;  };});

Example Usage

import { createSchema } from '@weaverse/hydrogen';
export let schema = createSchema({  type: 'product-showcase',  title: 'Product Showcase',  settings: [    {      group: 'Content',      inputs: [        {          type: 'product',          name: 'product',          label: 'Featured Product',          shouldRevalidate: true,        },      ],    },  ],  enabledOn: {    pages: ['INDEX', 'COLLECTION'],  },});
Previous← IMAGES_PLACEHOLDERS
NextWeaverse CLI →