Weaverse Hydrogen Components

Weaverse Components are the building blocks of your Hydrogen theme. They combine React’s component model with Weaverse’s powerful schema system to create customizable, performant sections for your storefront. This guide provides a comprehensive overview of how to create, configure, and optimize Weaverse components.

Getting Started

Component Registration

To use your components in Weaverse, you need to register them in your application:

// app/weaverse/components.ts
import type { HydrogenComponent } from '@weaverse/hydrogen';
import * as HeroImage from '~/sections/hero-image';
import * as RelatedProducts from '~/sections/related-products';

export const components: HydrogenComponent[] = [
  HeroImage,
  RelatedProducts,
  // Add more components...
];

// app/weaverse/index.tsx
import { WeaverseHydrogenRoot } from "@weaverse/hydrogen";
import { GenericError } from "~/components/root/generic-error";
import { components } from "./components";

export function WeaverseContent() {
  return (
    <WeaverseHydrogenRoot
      components={components}
      errorComponent={GenericError}
    />
  );
}

Core Concepts

What Makes a Weaverse Component?

A Weaverse Component consists of three essential parts:

Component Logic: A React component that renders your UI using TypeScript and modern React patterns
Schema Definition: Configuration that powers the visual editor in Weaverse Studio
Data Integration: Optional server-side data fetching for dynamic content

Component Lifecycle

A Weaverse component follows this lifecycle:

Component Creation: Define the component file
Schema Definition: Configure how the component appears in the editor
Component Logic: Implement the React component with proper props
Data Integration: Set up data fetching if needed
Render: Component is rendered on the page
Update: Component re-renders when props or state change
Cleanup: Component unmounts and cleans up resources

Component Structure

Basic Component Architecture

Every Weaverse component follows a consistent structure:

Imports: Import necessary types and utilities from Weaverse and React
Interface: Define the component’s props interface
Component: Create the component and pass the React 19 ref prop plus the remaining Weaverse props to its root DOM element
Schema: Export the schema that defines how the component appears in Weaverse Studio
Export: Export the component as default

Note about refs: Current Pilot uses React 19, where ref is a normal prop. Pass it to the root DOM element and spread the remaining Weaverse props so Studio can attach overlays and toolbars. Existing forwardRef components still work, but new components do not need it.

Basic Component Template

import type { HydrogenComponentProps } from '@weaverse/hydrogen';
import { createSchema } from '@weaverse/hydrogen';

interface MyComponentProps extends HydrogenComponentProps {
  // Add your custom props here
  title?: string;
  description?: string;
}

function MyComponent({ ref, title, description, children, ...rest }: MyComponentProps) {
  return (
    <section ref={ref} {...rest}>
      {title && <h2>{title}</h2>}
      {description && <p>{description}</p>}
      {children}
    </section>
  );
}

export let schema = createSchema({
  type: 'my-component',
  title: 'My Component',
  settings: [
    {
      group: 'Content',
      inputs: [
        {
          type: 'text',
          name: 'title',
          label: 'Title',
        },
        {
          type: 'textarea',
          name: 'description',
          label: 'Description',
        },
      ],
    },
  ],
});

export default MyComponent;

Key Elements

HydrogenComponentProps: Base props interface that all Weaverse components extend
ref and root props: Pass ref and the remaining Weaverse props to the component’s root DOM element
type property in schema: Unique identifier for the component (must be unique across all components)
settings: Defines the UI controls in Weaverse Studio
children prop: Components can render child components or elements

Advanced Component Structure

For more complex components, you may need to handle data loading, custom styling, or complex props management:

import { createSchema } from "@weaverse/hydrogen";
import { Await, useLoaderData } from "react-router";
import { Suspense, forwardRef } from "react";
import type { ProductCardFragment } from "storefront-api.generated";
import Heading, { type HeadingProps, headingInputs } from "~/components/heading";
import { ProductCard } from "~/components/product/product-card";
import { Section, type SectionProps, layoutInputs } from "~/components/section";
import { Swimlane } from "~/components/swimlane";

interface RelatedProductsProps
  extends Omit<SectionProps, "content">,
    Omit<HeadingProps, "as"> {
  headingTagName?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
}

const RelatedProducts = forwardRef<HTMLElement, RelatedProductsProps>((props, ref) => {
  const { recommended } = useLoaderData<{
    recommended: { nodes: ProductCardFragment[] };
  }>();
  
  const {
    headingTagName,
    content,
    size,
    mobileSize,
    desktopSize,
    color,
    weight,
    letterSpacing,
    alignment,
    minSize,
    maxSize,
    ...rest
  } = props;

  if (recommended) {
    return (
      <Section ref={ref} {...rest}>
        {content && (
          <Heading
            content={content}
            as={headingTagName}
            color={color}
            size={size}
            mobileSize={mobileSize}
            desktopSize={desktopSize}
            minSize={minSize}
            maxSize={maxSize}
            weight={weight}
            letterSpacing={letterSpacing}
            alignment={alignment}
          />
        )}
        <Suspense>
          <Await
            errorElement="There was a problem loading related products"
            resolve={recommended}
          >
            {(products) => (
              <Swimlane>
                {products.nodes.slice(0, 12).map((product) => (
                  <ProductCard
                    key={product.id}
                    product={product}
                    className="snap-start w-80"
                  />
                ))}
              </Swimlane>
            )}
          </Await>
        </Suspense>
      </Section>
    );
  }
  
  return <section ref={ref} {...rest} />;
});

export default RelatedProducts;

export let schema = createSchema({
  type: "related-products",
  title: "Related products",
  limit: 1,
  enabledOn: {
    pages: ["PRODUCT"],
  },
  settings: [
    {
      group: "Layout",
      inputs: layoutInputs.filter((i) => i.name !== "borderRadius"),
    },
    {
      group: "Heading",
      inputs: headingInputs.map((input) => {
        if (input.name === "as") {
          return {
            ...input,
            name: "headingTagName",
          };
        }
        return input;
      }),
    },
  ],
  presets: {
    gap: 32,
    width: "full",
    content: "You may also like",
  },
});

Component Types

1. Content Sections

Hero sections (images, videos)
Text blocks and rich content
Media galleries and sliders
Feature sections
Testimonial sections

2. E-commerce Components

Product displays
Collection grids
Related products
Product information
Cart components
Checkout components

3. Interactive Elements

Forms and newsletters
Reviews and testimonials
Maps and location displays
Countdown timers
Image hotspots

Schema Definition

The schema defines how your component appears and behaves in Weaverse Studio. It provides the configuration for the visual editor, allowing users to customize your component without writing code.

Schema Structure

export let schema = createSchema({
  type: 'component-type',      // Unique identifier
  title: 'Component Title',    // Display name in the Studio
  settings: [                 // Controls in the settings panel
    {
      group: 'Group Name',     // Groups related controls
      inputs: [
        {
          type: 'input-type',  // Type of input control
          name: 'inputName',   // Property name in the component
          label: 'Input Label', // Display label
          configs: {           // Type-specific configuration
            // Input-specific configurations
          },
        },
      ],
    },
  ],
  presets: {                   // Default values
    // Default values for properties
  },
  enabledOn: {                 // Page type restrictions
    pages: ['PAGE_TYPE'],
  },
  childTypes: ['component-type'], // Allowed child components
  limit: 1,                    // Maximum instances
});

Common Input Types

Basic Inputs
- text: Single-line text input
- textarea: Multi-line text input
- richtext: Rich text editor with formatting
- number: Numeric input
- color: Color picker
- toggle: Boolean switch
- select: Dropdown selection
- range: Slider input
- toggle-group: Group of exclusive options
Media Inputs
- image: Image selector
- video: Video selector
- file: File selector
Layout Inputs
- position: Position selector (top/center/bottom, left/center/right)
- spacing: Margin and padding controls
- alignment: Text alignment controls
Special Inputs
- product: Product selector
- collection: Collection selector
- datepicker: Date and time selector
- heading: Section divider with heading

Input Configuration

Each input type has specific configuration options:

// Select input example
{
  type: "select",
  name: "height",
  label: "Section height",
  configs: {
    options: [
      { value: "small", label: "Small" },
      { value: "medium", label: "Medium" },
      { value: "large", label: "Large" },
    ],
  },
  defaultValue: "medium",
  helpText: "Controls the height of the section",
}

// Range input example
{
  type: "range",
  name: "opacity",
  label: "Opacity",
  configs: {
    min: 0,
    max: 100,
    step: 5,
    unit: "%",
  },
  defaultValue: 100,
}

// Toggle group example
{
  type: "toggle-group",
  name: "alignment",
  label: "Content alignment",
  configs: {
    options: [
      { value: "left", label: "Left", icon: "align-start-vertical" },
      { value: "center", label: "Center", icon: "align-center-vertical" },
      { value: "right", label: "Right", icon: "align-end-vertical" },
    ],
  },
  defaultValue: "center",
}

Advanced Schema Example

export let schema = createSchema({
  type: "hero-image",
  title: "Hero image",
  settings: [
    {
      group: "Layout",
      inputs: [
        {
          type: "select",
          name: "height",
          label: "Section height",
          configs: {
            options: [
              { value: "small", label: "Small" },
              { value: "medium", label: "Medium" },
              { value: "large", label: "Large" },
              { value: "full", label: "Fullscreen" },
            ],
          },
        },
        {
          type: "position",
          name: "contentPosition",
          label: "Content position",
          defaultValue: "center center",
        },
        ...layoutInputs.filter(
          (inp) => inp.name !== "divider" && inp.name !== "borderRadius",
        ),
      ],
    },
    {
      group: "Background",
      inputs: [
        ...backgroundInputs.filter(
          (inp) =>
            inp.name !== "backgroundFor" && inp.name !== "backgroundColor",
        ),
      ],
    },
    { group: "Overlay", inputs: overlayInputs },
  ],
  childTypes: ["subheading", "heading", "paragraph", "button"],
  presets: {
    height: "large",
    contentPosition: "center center",
    backgroundImage: IMAGES_PLACEHOLDERS.banner_1,
    backgroundFit: "cover",
    enableOverlay: true,
    overlayOpacity: 40,
    children: [
      {
        type: "subheading",
        content: "Subheading",
        color: "#ffffff",
      },
      {
        type: "heading",
        content: "Hero image with text overlay",
        as: "h2",
        color: "#ffffff",
        size: "default",
      },
      {
        type: "paragraph",
        content:
          "Use this text to share information about your brand with your customers.",
        color: "#ffffff",
      },
    ],
  },
});

Data Integration

In a Weaverse Hydrogen project, there are two distinct types of loader functions:

Route Loaders: These loaders are used in React Router v7 route files (app/routes/**/*.tsx) and follow the React Router conventions
Weaverse Component Loaders: These loaders are defined in Weaverse component files and enable server-side data fetching at the component level

Route Loaders

In React Router route files, you define loaders that run on the server and provide data to all components rendered by that route:

// app/routes/products/product.tsx
import type { LoaderFunctionArgs } from 'react-router';
import { useLoaderData } from 'react-router';

export async function loader({ params, context }: LoaderFunctionArgs) {
  const { productHandle: handle } = params;
  const { storefront } = context;

  const { product } = await storefront.query(PRODUCT_QUERY, {
    variables: { handle },
  });

  // Return a plain object — `json()` is no longer needed in React Router v7
  return { product };
}

export default function ProductRoute() {
  const { product } = useLoaderData<typeof loader>();
  
  return (
    <div>
      <h1>{product.title}</h1>
      {/* Weaverse content rendering goes here */}
      <WeaverseContent />
    </div>
  );
}

Weaverse Component Loaders

Weaverse components can define their own loaders, which fetch data specifically for that component. This allows for more modular and reusable components that bring their own data:

// app/sections/featured-product/index.tsx
import type {
  ComponentLoaderArgs,
  HydrogenComponentProps,
  WeaverseProduct,
} from '@weaverse/hydrogen';
import { PRODUCT_QUERY } from '~/graphql/queries';

interface FeaturedProductData {
  product: WeaverseProduct;
}

export const loader = async (args: ComponentLoaderArgs<FeaturedProductData>) => {
  const { weaverse, data } = args;
  const { storefront } = weaverse;
  
  if (!data?.product?.handle) {
    return null;
  }
  
  const { product } = await storefront.query(PRODUCT_QUERY, {
    variables: {
      handle: data.product.handle,
    },
  });

  return { product };
};

type FeaturedProductProps = HydrogenComponentProps<Awaited<ReturnType<typeof loader>>> & FeaturedProductData;

function FeaturedProduct({ ref, loaderData, product: selectedProduct, ...rest }: FeaturedProductProps) {
  const product = loaderData?.product;
  
  if (!product) {
    return <section ref={ref} {...rest}>Select a product in the editor</section>;
  }
  
  return (
    <section ref={ref} {...rest}>
      <h2>{product.title}</h2>
      <p>{product.description}</p>
      {/* Product details */}
    </section>
  );
}

export default FeaturedProduct;

export let schema = createSchema({
  type: 'featured-product',
  title: 'Featured Product',
  settings: [
    {
      group: 'Product',
      inputs: [
        {
          type: 'product',
          name: 'product',
          label: 'Product',
        },
      ],
    },
  ],
});

Key Differences

Scope:
- Route loaders provide data to an entire route
- Weaverse component loaders provide data only to the specific component
Access:
- Route loader data is accessed via the useLoaderData() hook
- Weaverse component loader data is received via props.loaderData
Arguments:
- Route loaders receive { params, request, context }
- Weaverse component loaders receive { weaverse, data } where:
  - weaverse: The WeaverseClient instance — Storefront API access, fetchWithCache, env, and the current request
  - data: Contains the component’s configured data from the editor
There is no context argument in ComponentLoaderArgs. Reach the incoming request through weaverse.request.
Use cases:
- Use route loaders for route-level data like page information
- Use Weaverse component loaders for component-specific data

Data Flow Between Components

Components can access data from their parent components using the useParentInstance hook:

import { useParentInstance } from '@weaverse/hydrogen';

function ChildComponent() {
  const parent = useParentInstance();
  const data = parent.data.loaderData;
  // Use the data from parent component
}

Data Fetching Best Practices

Type Safety: Always define proper TypeScript interfaces for your loader data:

interface ComponentData {
  // Define your data structure
}

export async function loader(args: ComponentLoaderArgs): Promise<ComponentData> {
  // Fetch data
  return data;
}

Error Handling: Implement proper error handling in your loaders:

export async function loader({ weaverse }: ComponentLoaderArgs) {
  try {
    const data = await fetchData(weaverse);
    return { data };
  } catch (error) {
    console.error('Error fetching data:', error);
    return { data: null, error: 'Failed to load data' };
  }
}

Data Transformation: Transform data in the loader before passing it to the component:

export async function loader({ weaverse }: ComponentLoaderArgs) {
  const rawData = await fetchData(weaverse);
  return {
    data: transformData(rawData), // Transform data for easier consumption
  };
}

Caching: Leverage Hydrogen’s built-in caching mechanisms and Weaverse’s utilities for improved performance:

import { CacheLong } from '@shopify/hydrogen';

export async function loader({ weaverse }: ComponentLoaderArgs) {
  const { storefront, fetchWithCache } = weaverse;

  // Using Weaverse's fetchWithCache utility (recommended)
  // Signature: fetchWithCache(url, options) — the cache strategy goes in `options.strategy`
  const data = await fetchWithCache(
    'https://api.example.com/data',
    {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
      },
      strategy: CacheLong(), // Use appropriate cache strategy
    }
  );

  // POST requests work the same way — the body is part of the cache key
  const product = await fetchWithCache(
    'https://my-api.com/data',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ id: 'my-product' }),
      strategy: CacheLong(),
    }
  );

  // Or using storefront API with caching
  const { collection } = await storefront.query(
    `query CollectionDetails($handle: String!) {
      collection(handle: $handle) {
        title
        description
      }
    }`,
    {
      variables: {
        handle: 'summer-collection',
      },
      cache: CacheLong(), // Cache for a long time (1 day by default)
    }
  );
  
  return { product, collection, data };
}

Weaverse’s fetchWithCache is a convenient utility that simplifies cached data fetching from external APIs:

Available on the weaverse loader argument as weaverse.fetchWithCache
Takes exactly two arguments: fetchWithCache(url, options)
Automatically handles JSON parsing
Applies the caching strategy passed as options.strategy (defaults to a short custom strategy)
Includes the URL, method, body, and project ID in the cache key, so POST requests cache correctly
Bypasses the cache automatically while in Studio design mode

Hydrogen provides several caching strategies out of the box:

CacheNone(): No caching, always fetches fresh data
CacheShort(): Short-term caching (a few minutes)
CacheLong(): Long-term caching (1 day by default)
cache.with(): Custom cache control

You can also customize cache durations:

import { CacheLong } from '@shopify/hydrogen';

// Cache for 60 seconds
const cacheStrategy = CacheLong({
  maxAge: 60,
  staleWhileRevalidate: 10,
});

// Use with Weaverse's fetchWithCache
const data = await weaverse.fetchWithCache(
  'https://api.example.com/data',
  { method: 'GET', strategy: cacheStrategy }
);

// Or use in storefront query
const data = await storefront.query(QUERY, {
  variables,
  cache: cacheStrategy,
});

For more details, see Hydrogen Documentation on Caching.

Component Organization Patterns

1. Parent-Child Component Structure

// Parent component (image-with-text.tsx)
import { ImageWithTextContent } from './content';
import { ImageWithTextImage } from './image';

const ImageWithText = forwardRef<HTMLElement, ImageWithTextProps>((props, ref) => {
  return (
    <section ref={ref}>
      <ImageWithTextContent />
      <ImageWithTextImage />
    </section>
  );
});

// Child component (content.tsx)
const ImageWithTextContent = forwardRef<HTMLDivElement, ImageWithTextContentProps>((props, ref) => {
  return (
    <div ref={ref}>
      {props.children}
    </div>
  );
});

export let schema = createSchema({
  type: "image-with-text--content",
  title: "Content",
  limit: 1,
  childTypes: ["subheading", "heading", "paragraph", "button"],
  // ... schema configuration
});

2. Reusable Component Parts

// Reusable component part (hotspots/item.tsx)
interface HotspotsItemData {
  icon: "circle" | "plus" | "bag" | "tag";
  iconSize: number;
  offsetX: number;
  offsetY: number;
  product: WeaverseProduct;
  popupWidth: number;
  showPrice: boolean;
  showViewDetailsLink: boolean;
  viewDetailsLinkText: string;
}

const HotspotsItem = forwardRef<HTMLDivElement, HotspotsItemProps>((props, ref) => {
  const {
    icon,
    iconSize,
    offsetX,
    offsetY,
    product,
    popupWidth,
    showPrice,
    showViewDetailsLink,
    viewDetailsLinkText,
    children,
    loaderData,
    ...rest
  } = props;

  return (
    <div
      ref={ref}
      {...rest}
      className="absolute -translate-x-1/2 -translate-y-1/2 hover:z-[1]"
      style={{
        top: `${offsetY}%`,
        left: `${offsetX}%`,
      } as CSSProperties}
    >
      {/* Component content */}
    </div>
  );
});

Styling Patterns

1. CVA for Variant Management

import { cva } from "class-variance-authority";
import type { VariantProps } from "class-variance-authority";

const variants = cva("flex flex-col", {
  variants: {
    height: {
      small: "min-h-[40vh] lg:min-h-[50vh]",
      medium: "min-h-[50vh] lg:min-h-[60vh]",
      large: "min-h-[70vh] lg:min-h-[80vh]",
      full: "h-screen",
    },
    contentPosition: {
      "center center": "justify-center items-center text-center",
      "top left": "justify-start items-start text-left",
      // ... more positions
    },
  },
  defaultVariants: {
    height: "large",
    contentPosition: "center center",
  },
});

interface ComponentProps extends VariantProps<typeof variants> {
  // Additional props
}

2. CSS Custom Properties

const Component = forwardRef<HTMLElement, ComponentProps>((props, ref) => {
  const { textColor, ...rest } = props;
  
  const style = {
    "--timer-color": textColor,
  } as CSSProperties;
  
  return (
    <div
      ref={ref}
      {...rest}
      className="countdown--timer flex text-[var(--timer-color)]"
      style={style}
    >
      {/* Component content */}
    </div>
  );
});

Interactive Components

1. Countdown Timer

const CountdownTimer = forwardRef<HTMLElement, CountdownTimerProps>((props, ref) => {
  const { endTime, ...rest } = props;
  const [remainingTime, setRemainingTime] = useState(calculateRemainingTime(endTime));

  useEffect(() => {
    const intervalId = setInterval(() => {
      const updatedTimeRemaining = calculateRemainingTime(endTime);
      setRemainingTime(updatedTimeRemaining);
      
      if (isTimeUp(updatedTimeRemaining)) {
        clearInterval(intervalId);
      }
    }, 1000);

    return () => clearInterval(intervalId);
  }, [endTime]);

  return (
    <div ref={ref} {...rest}>
      {/* Timer display */}
    </div>
  );
});

2. Hotspots

const Hotspots = forwardRef<HTMLElement, HotspotsProps>((props, ref) => {
  const { items, ...rest } = props;
  
  return (
    <div ref={ref} {...rest} className="relative">
      {items.map((item) => (
        <HotspotsItem key={item.id} {...item} />
      ))}
    </div>
  );
});

Best Practices

1. Using CVA with Select Inputs

Class Variance Authority (CVA) provides an elegant way to handle component variants that map directly to schema select inputs. This pattern creates a strong connection between your schema inputs and component styling:

// Example from hero-image.tsx
import { type VariantProps, cva } from "class-variance-authority";

// Define variants using CVA
const variants = cva("flex flex-col [&_.paragraph]:mx-[unset]", {
  variants: {
    height: {
      small: "min-h-[40vh] lg:min-h-[50vh]",
      medium: "min-h-[50vh] lg:min-h-[60vh]",
      large: "min-h-[70vh] lg:min-h-[80vh]",
      full: "",
    },
    contentPosition: {
      "top left": "justify-start items-start [&_.paragraph]:[text-align:left]",
      "top center": "justify-start items-center [&_.paragraph]:[text-align:center]",
      "top right": "justify-start items-end [&_.paragraph]:[text-align:right]",
      "center left": "justify-center items-start [&_.paragraph]:[text-align:left]",
      "center center": "justify-center items-center [&_.paragraph]:[text-align:center]",
      "center right": "justify-center items-end [&_.paragraph]:[text-align:right]",
      "bottom left": "justify-end items-start [&_.paragraph]:[text-align:left]",
      "bottom center": "justify-end items-center [&_.paragraph]:[text-align:center]",
      "bottom right": "justify-end items-end [&_.paragraph]:[text-align:right]",
    },
  },
  defaultVariants: {
    height: "large",
    contentPosition: "center center",
  },
});

// Extend component props with CVA variants
export interface HeroImageProps extends VariantProps<typeof variants> {}

// Use variants in component
const HeroImage = forwardRef<HTMLElement, HeroImageProps & SectionProps>(
  (props, ref) => {
    const { children, height, contentPosition, ...rest } = props;
    
    return (
      <Section
        ref={ref}
        {...rest}
        containerClassName={variants({
          contentPosition,
          height,
        })}
      >
        {children}
      </Section>
    );
  },
);

// Define schema with matching select inputs
export let schema = createSchema({
  type: "hero-image",
  title: "Hero image",
  settings: [
    {
      group: "Layout",
      inputs: [
        {
          type: "select",
          name: "height",
          label: "Section height",
          configs: {
            options: [
              { value: "small", label: "Small" },
              { value: "medium", label: "Medium" },
              { value: "large", label: "Large" },
              { value: "full", label: "Fullscreen" },
            ],
          },
        },
        {
          type: "position",
          name: "contentPosition",
          label: "Content position",
          defaultValue: "center center",
        },
        // ... more inputs
      ],
    },
    // ... more groups
  ],
  // ... schema continues
});

Benefits of this approach:

Type Safety: CVA provides type checking for variant values
Single Source of Truth: Variant options in schema match exact keys in CVA
Maintainability: Changes to variant names only need to happen in one place
Composition: Easily combine multiple variants for complex styling
Default Values: Set defaults in CVA that match schema defaults
Responsive Design: Apply responsive styles within variant definitions

This pattern works particularly well for components with multiple configurable aspects like layout, sizing, positioning, or appearance variants.

2. Component Architecture

Use TypeScript for better type safety
- Define explicit prop interfaces
- Use generics for reusable components
- Utilize TypeScript’s utility types for prop manipulation
Follow React’s Best Practices
- With React 19, accept ref as a prop and pass it to the root DOM element; keep forwardRef only for existing components that already use it
- Separate component logic from presentation
- Extract reusable UI elements into smaller components
- Use composition over inheritance
Optimize Component Structure
- Keep components focused on a single responsibility
- Create dedicated files for types and utilities
- Use meaningful names for components and props
- Document complex logic with comments

3. State Management

import { useState, useReducer } from 'react';

// Simple state management with useState
const SimpleComponent = forwardRef<HTMLElement, SimpleComponentProps>((props, ref) => {
  const [isOpen, setIsOpen] = useState(false);
  
  return (
    <section ref={ref}>
      <button onClick={() => setIsOpen(!isOpen)}>Toggle</button>
      {isOpen && <div>Content</div>}
    </section>
  );
});

// Complex state management with useReducer
function reducer(state, action) {
  switch (action.type) {
    case 'increment':
      return { count: state.count + 1 };
    case 'decrement':
      return { count: state.count - 1 };
    default:
      throw new Error();
  }
}

const ComplexComponent = forwardRef<HTMLElement, ComplexComponentProps>((props, ref) => {
  const [state, dispatch] = useReducer(reducer, { count: 0 });
  
  return (
    <section ref={ref}>
      Count: {state.count}
      <button onClick={() => dispatch({ type: 'increment' })}>+</button>
      <button onClick={() => dispatch({ type: 'decrement' })}>-</button>
    </section>
  );
});

4. Error Handling

import { ErrorBoundary } from 'react-error-boundary';

const ErrorFallback = ({ error, resetErrorBoundary }) => {
  return (
    <div role="alert">
      <p>Something went wrong:</p>
      <pre>{error.message}</pre>
      <button onClick={resetErrorBoundary}>Try again</button>
    </div>
  );
};

const SafeComponent = forwardRef<HTMLElement, SafeComponentProps>((props, ref) => {
  return (
    <ErrorBoundary FallbackComponent={ErrorFallback}>
      <section ref={ref}>
        {/* Component content */}
      </section>
    </ErrorBoundary>
  );
});

5. Accessibility

Follow WAI-ARIA Guidelines
- Use semantic HTML elements
- Add proper ARIA attributes
- Ensure keyboard navigation works
- Provide sufficient color contrast

const AccessibleComponent = forwardRef<HTMLElement, AccessibleComponentProps>((props, ref) => {
  const { ariaLabel, ariaDescribedby, ...rest } = props;
  
  return (
    <section 
      ref={ref} 
      role="region"
      aria-label={ariaLabel}
      aria-describedby={ariaDescribedby}
      tabIndex={0}
      {...rest}
    >
      {/* Component content */}
    </section>
  );
});

6. Performance Considerations

Memoize expensive calculations with useMemo
Optimize callback functions with useCallback
Use React.memo for components that render often but rarely change
Implement virtualization for long lists
Lazy load components that aren’t immediately visible

Troubleshooting

Common Issues

Component not appearing in Studio
- Verify component registration in components.ts
- Check schema type uniqueness across all components
- Ensure all required props are handled in the component
- Check for syntax errors in the component or schema
- Verify the component is exported correctly (both default export and schema)
Component not selectable in Studio
- Usually caused by not spreading ...rest onto the root DOM element, or returning null
- See the Component Not Selectable troubleshooting guide for detailed fixes
Schema not updating
- Clear browser cache and refresh the page
- Restart development server to reload all components
- Verify schema syntax is correct
- Check browser console for errors
- Ensure component and schema are properly exported
Data loading issues
- Check loader implementation for errors
- Verify data types match what’s expected
- Implement error boundaries to catch and display errors
- Add logging to debug data loading process
- Check network requests in browser DevTools
Styling issues
- Check for CSS conflicts with other components
- Verify class names are being applied correctly
- Inspect the DOM to see which styles are actually applied
- Test with inline styles to isolate CSS framework issues
- Check for responsive design breakpoints

Debugging Tips

// Add debug logging
const DebugComponent = forwardRef<HTMLElement, DebugComponentProps>((props, ref) => {
  console.log('Props:', props);
  
  // Track re-renders
  useEffect(() => {
    console.log('Component rendered');
    return () => console.log('Component unmounted');
  }, []);
  
  // Debug specific prop changes
  useEffect(() => {
    console.log('Specific prop changed:', props.specificProp);
  }, [props.specificProp]);
  
  return (
    <section ref={ref}>
      {/* Component content */}
    </section>
  );
});

Development Environment Setup

For effective debugging:

Enable React DevTools in your browser
Use VS Code with TypeScript support for real-time type checking
Configure ESLint with React and TypeScript rules
Set up source maps for better debugging in development
Use Chrome DevTools to inspect components and network requests

Next Steps

Learn about Component Schema for advanced schema configuration
Explore Data Fetching for more data integration patterns
See Example Components for inspiration and reference implementations
Join our Community for support and sharing best practices

Conclusion

Building Weaverse components requires understanding the interplay between React components, schema configuration, and data integration. By following the patterns and practices outlined in this guide, you can create powerful, customizable, and performant components that enhance your Hydrogen theme. Remember that great components are:

Reusable: They can be used in multiple contexts
Customizable: They provide sensible defaults but allow for customization
Accessible: They follow web accessibility guidelines
Performant: They load quickly and render efficiently
Maintainable: They follow clean code principles and are well-documented

As you build your Weaverse components, focus on creating a consistent user experience while enabling flexibility and customization through the schema system.

​Weaverse Hydrogen Components

​Getting Started

​Component Registration

​Core Concepts

​What Makes a Weaverse Component?

​Component Lifecycle

​Component Structure

​Basic Component Architecture

​Basic Component Template

​Key Elements

​Advanced Component Structure

​Component Types

​1. Content Sections

​2. E-commerce Components

​3. Interactive Elements

​Schema Definition

​Schema Structure

​Common Input Types

​Input Configuration

​Advanced Schema Example

​Data Integration

​Route Loaders

​Weaverse Component Loaders

​Key Differences

​Data Flow Between Components

​Data Fetching Best Practices

​Component Organization Patterns

​1. Parent-Child Component Structure

​2. Reusable Component Parts

​Styling Patterns

​1. CVA for Variant Management

​2. CSS Custom Properties

​Interactive Components

​1. Countdown Timer

​2. Hotspots

​Best Practices

​1. Using CVA with Select Inputs

​2. Component Architecture

​3. State Management

​4. Error Handling

​5. Accessibility

​6. Performance Considerations

​Troubleshooting

​Common Issues

​Debugging Tips

​Development Environment Setup

​Next Steps

​Conclusion