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. Theinspector
property itself has been deprecated in favor ofsettings
.
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 ofsettings
. Whileinspector
is still supported for backward compatibility, new theme schemas should usesettings
.
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
- WeaverseHydrogenRoot - The main component that uses these types
- WeaverseClient - Client for fetching Weaverse content
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'], },});