​

How Weaverse Works

​

Supported Storefronts

• Shopify Hydrogen: a Hydrogen storefront with the Weaverse integration, such as a project based on Pilot.
• Next.js App Router: a Shopify headless storefront using the supported @weaverse/hydrogen/next integration. See the Next.js integration guide.

​

Shopify Store Domain vs. Studio Preview URL

• Shopify store domain: your-store.myshopify.com identifies the Shopify store used for commerce data. It is not the headless application’s preview address. The storefront served at this address normally belongs to Shopify’s Liquid-based Online Store.
• Studio preview URL: the address of your running, Weaverse-integrated headless application. For the local Hydrogen quickstart, this is http://localhost:3456. For a hosted setup, use the actual deployed application’s URL.

​

What the Shopify App Does

​

Set Up and Verify Your Headless Storefront

1. Use a supported storefront. Follow the Hydrogen quickstart to set up a Weaverse-integrated storefront, or connect an existing storefront with the appropriate Weaverse integration. A store using only a Liquid theme is not enough.
2. Confirm the headless application loads. Open its preview URL directly. If testing on another machine, use a reachable hosted preview; localhost refers to the machine running the browser.
3. Connect Studio to that application. Open the corresponding Weaverse project. If Studio shows Preview Connection Lost, use Manage previews to check that the selected URL belongs to the running headless application, not the store’s Liquid storefront.
4. Verify visual editing. Open a page containing Weaverse sections, select a section, change an available content setting, and confirm the change appears in Studio’s preview. Use the project’s normal save and publish workflow to verify the result on that headless storefront.
5. Check the correct output. The expected result is on the connected headless storefront. The store’s separate Liquid theme is not the output of this workflow.

​

Architecture Overview

​

The Weaverse Workflow

​

1. Developer Experience

// app/sections/product-card/index.tsx
// You write React components with schemas
import { createSchema, type WeaverseComponentProps } from '@weaverse/hydrogen/react-router'

interface ProductCardProps extends WeaverseComponentProps {
  title: string
  price: string
}

function ProductCard({ ref, title, price, ...rest }: ProductCardProps) {
  return <div ref={ref} {...rest}>{title} - {price}</div>
}

export default ProductCard

export const schema = createSchema({
  type: 'product-card',
  title: 'Product Card',
  settings: [/* configuration */],
})

// app/weaverse/components.ts
import type { WeaverseComponent } from '@weaverse/hydrogen/react-router'
import * as ProductCard from '~/sections/product-card'

export const components: WeaverseComponent[] = [ProductCard]

​

2. Merchant Experience

• Merchants drag components onto pages
• Real-time preview across all devices
• Intuitive settings panels for customization
• No code required

• Create and manage pages visually
• Organize content with sections and components
• Preview changes before publishing

​

3. Runtime Performance

• Pages are server-rendered by Hydrogen on each request, using the page data loaded from Weaverse
• The Studio editing bridge only loads in design mode, not on the live storefront
• Only your component logic ships to browsers

• Automatic image optimization
• Code splitting by route
• Server-side rendering with Hydrogen

​

Key Concepts

​

Components vs Sections

• Buttons, cards, forms
• Configured through props
• Can be used multiple times per page

• Headers, hero areas, footers
• Container multiple components
• Define page structure

​

Schema-Driven Configuration

import { createSchema } from '@weaverse/hydrogen/react-router'

export const schema = createSchema({
  type: 'unique-component-name',
  title: 'Human-readable Title',
  settings: [
    {
      group: 'Content',
      inputs: [
        {
          type: 'text',
          name: 'heading',
          label: 'Heading Text',
          defaultValue: 'Hello World'
        }
      ]
    }
  ]
})

• Visual editor controls
• Validation rules
• Default values

​

Data Flow

1. Build Time: Schemas define available components
2. Edit Time: Merchants configure component instances
3. Request Time: Hydrogen loads the page data from Weaverse and server-renders the HTML
4. Hydration: Interactive components become functional

​

Integration with Hydrogen

• React Router v7: Route modules with loaders and type-safe route config
• Streaming SSR: Fast initial page loads with deferred non-critical data
• Shopify APIs: Native product and cart integration
• Performance: Optimized for Core Web Vitals

​

Development Modes

​

Local Development

• Hot reload for instant feedback
• Weaverse Studio runs alongside your app
• Real-time component updates

​

Production

• Components are pre-built and optimized
• Merchants edit through hosted Weaverse Studio
• Changes deploy through your CI/CD pipeline

​

Benefits

• Full control over component logic
• Modern React development experience
• No vendor lock-in
• Standard deployment workflows

• Visual page building
• No technical knowledge required
• Real-time preview
• Mobile-responsive editing

• Fast loading pages
• Mobile-optimized experiences
• Consistent brand presentation
• Accessible by default

​

Next Steps

• Learn about Project Structure
• Start building with the Development Guide
• Explore the API Reference for advanced usage