Build Your First Weaverse Hydrogen Store

This tutorial walks through building a modern Shopify Hydrogen storefront with visual customization capabilities. By the end, you’ll have a live store that you and your team can edit through Weaverse Studio.

What You’ll Build

Modern Shopify storefront with React Router v7 and React 19
Visual editing capabilities through Weaverse Studio
Custom components with schema-driven configurations
Production-ready deployment on Shopify Oxygen

Prerequisites

Before starting, ensure you have:

Node.js 22.12 or newer (required by the current Pilot project; check with node --version)
Shopify store (any plan, development store works fine)
Basic knowledge of React, TypeScript, and Shopify concepts
Time to configure your Shopify credentials, customize the theme, and deploy it

New to these technologies? Review these resources first:

Part 1: Quick Start (5 minutes)

Install Weaverse Studio

Go to Shopify App Store: Visit Weaverse on Shopify App Store
Install the app on your Shopify store
Open Weaverse from your Shopify admin dashboard

Create Your First Project

Click “Create Project” in Weaverse Studio
Choose the Pilot theme (recommended starter theme)
Name your project (e.g., “My Store”)
Click “Create”

🎉 Success! You now have a Weaverse project with the Pilot theme. You can see the visual editor with pre-built sections ready to customize.

Part 2: Local Development Setup (10 minutes)

Set Up Your Development Environment

Clone the Pilot theme:

git clone https://github.com/weaverse/pilot.git my-weaverse-store
cd my-weaverse-store

Install dependencies:
npm install
Set up environment variables: Create a .env file in your project root:
# Copy from the example cp .env.example .env
Update .env with your store details:
# Required - Get from Weaverse Studio WEAVERSE_PROJECT_ID="your-project-id-from-studio" # Required - Your Shopify store PUBLIC_STORE_DOMAIN="your-store.myshopify.com" PUBLIC_STOREFRONT_API_TOKEN="your-storefront-access-token" # Required - generated automatically by Weaverse CLI/agent setup SESSION_SECRET="<generated-random-secret>" # Optional - For customer accounts PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID="your-client-id" PUBLIC_CUSTOMER_ACCOUNT_API_URL="https://your-store.myshopify.com/api/2023-04/graphql"
Where to find these values:
- WEAVERSE_PROJECT_ID: Copy from Weaverse Studio project settings
- PUBLIC_STORE_DOMAIN and PUBLIC_STOREFRONT_API_TOKEN:
  - Stores on a Shopify plan: install the Hydrogen sales channel (https://apps.shopify.com/hydrogen), create one Hydrogen storefront project, then run npx shopify hydrogen env pull or copy values from Hydrogen sales channel → Storefront Settings → Environments and variables.
  - Development stores or stores without a Shopify plan: install the Headless sales channel (https://apps.shopify.com/headless), then copy the Storefront API values into .env or give them to your AI agent to handle.
- SESSION_SECRET: Generated automatically by the Weaverse CLI/agent setup. For manual setup, generate with openssl rand -hex 32.
Start the development server:
npm run dev
Your store will be available at: http://localhost:3456

Connect to Weaverse Studio

Open Weaverse Studio in another browser tab
Go to Project Settings → Preview URL
Set Preview URL to http://localhost:3456
Save changes

Change or manage preview control in Weaverse Studio

Manage previews dialog with local development URL

✅ Checkpoint: You should now see your local development server in Weaverse Studio’s preview panel. Changes in Studio should appear immediately in your local site.

Part 3: Understanding Weaverse Architecture (5 minutes)

How Weaverse Works

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Weaverse      │───▶│   Your Local    │───▶│   Production    │
│   Studio        │    │   Development   │    │   (Oxygen)      │
│   (Visual CMS)  │    │   Server        │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Weaverse Studio: Visual editor where you and your team create content Your Code: React components with schemas that define what’s editable Production: Shopify Oxygen hosting your fast, static-generated site

Key Concepts

Components: React components that render sections of your store Schemas: Define what users can edit in Studio (text, images, colors, etc.) Loaders: Fetch data from Shopify (products, collections, etc.) Studio: No-code visual editor for content creators

Part 4: Build Your First Component (15 minutes)

Let’s create a customizable Hero Banner that showcases your products.

Create the Component

Create the component file:

mkdir -p app/sections/hero-banner
touch app/sections/hero-banner/index.tsx

Add the Hero Banner component:

// app/sections/hero-banner/index.tsx
import { Image } from '@shopify/hydrogen';
import { createSchema } from '@weaverse/hydrogen';
import type { HydrogenComponentProps } from '@weaverse/hydrogen';

interface HeroBannerProps extends HydrogenComponentProps {
  heading: string;
  description: string;
  buttonText: string;
  buttonLink: string;
  backgroundImage: {
    url: string;
    altText: string;
    width: number;
    height: number;
  };
}

function HeroBanner(props: HeroBannerProps) {
  const { 
    heading, 
    description, 
    buttonText, 
    buttonLink, 
    backgroundImage,
    ...rest 
  } = props;

  return (
    <section {...rest} className="relative min-h-[500px] flex items-center justify-center overflow-hidden">
      {/* Background Image */}
      {backgroundImage && (
        <div className="absolute inset-0 z-0">
          <Image
            data={backgroundImage}
            className="w-full h-full object-cover"
            sizes="100vw"
          />
          <div className="absolute inset-0 bg-black/40" />
        </div>
      )}
      
      {/* Content */}
      <div className="relative z-10 text-center text-white max-w-4xl mx-auto px-6">
        <h1 className="text-4xl md:text-6xl font-bold mb-6">
          {heading}
        </h1>
        <p className="text-lg md:text-xl mb-8 opacity-90">
          {description}
        </p>
        {buttonText && buttonLink && (
          <a
            href={buttonLink}
            className="inline-block bg-white text-black px-8 py-3 rounded-lg font-semibold hover:bg-gray-100 transition-colors"
          >
            {buttonText}
          </a>
        )}
      </div>
    </section>
  );
}

export default HeroBanner;

export 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: 'textarea',
          name: 'description',
          label: 'Description',
          defaultValue: 'Discover amazing products that will transform your life.',
        },
        {
          type: 'text',
          name: 'buttonText',
          label: 'Button Text',
          defaultValue: 'Shop Now',
        },
        {
          type: 'text',
          name: 'buttonLink',
          label: 'Button Link',
          defaultValue: '/collections/all',
        },
      ],
    },
    {
      group: 'Design',
      inputs: [
        {
          type: 'image',
          name: 'backgroundImage',
          label: 'Background Image',
        },
      ],
    },
  ],
});

Register the Component

Add to components registry:

// app/weaverse/components.ts
import * as HeroBanner from '~/sections/hero-banner';

export let components: HydrogenComponent[] = [
  // ... existing components
  HeroBanner,
];

Test Your Component

Go to Weaverse Studio
Click “Add Section”
Select “Hero Banner”
Customize the content using the settings panel
Upload a background image
See changes appear instantly in your local preview

🎯 Achievement Unlocked: You’ve created your first Weaverse component with full visual editing capabilities!

Part 5: Advanced Features (10 minutes)

Add Dynamic Product Data

Let’s enhance our Hero Banner to feature a specific product.

Create a product loader:

// Add to app/sections/hero-banner/index.tsx

import type { ComponentLoaderArgs } from '@weaverse/hydrogen';

export async function loader(args: ComponentLoaderArgs<HeroBannerProps>) {
  const { weaverse } = args;
  const { storefront } = weaverse;

  // A `product` input stores a resource reference, not a bare string —
  // read the handle off it before querying the Storefront API.
  const handle = args.data?.product?.handle;
  if (!handle) {
    return null;
  }

  const { product } = await storefront.query(`
    query GetProduct($handle: String!) {
      product(handle: $handle) {
        id
        title
        handle
        description
        featuredImage {
          url
          altText
          width
          height
        }
        priceRange {
          minVariantPrice {
            amount
            currencyCode
          }
        }
      }
    }
  `, {
    variables: { handle }
  });

  return { product };
}

Update component to use product data:

import type { WeaverseProduct } from '@weaverse/hydrogen';

interface HeroBannerProps extends HydrogenComponentProps {
  // ... existing props
  product?: WeaverseProduct;
  loaderData?: {
    product?: any;
  };
}

function HeroBanner(props: HeroBannerProps) {
  const { loaderData, product: _product, ...rest } = props;
  const product = loaderData?.product;

  // Use product data if available
  const displayHeading = product?.title || props.heading;
  const displayDescription = product?.description || props.description;
  const displayImage = product?.featuredImage || props.backgroundImage;

  return (
    <section {...rest} className="relative min-h-[500px] flex items-center justify-center overflow-hidden">
      {/* ... rest of component */}
      <div className="relative z-10 text-center text-white max-w-4xl mx-auto px-6">
        <h1 className="text-4xl md:text-6xl font-bold mb-6">
          {displayHeading}
        </h1>
        <p className="text-lg md:text-xl mb-8 opacity-90">
          {displayDescription}
        </p>
        {product && (
          <p className="text-2xl font-bold mb-4">
            From ${product.priceRange.minVariantPrice.amount}
          </p>
        )}
        {/* ... button code */}
      </div>
    </section>
  );
}

Add product selector to schema:

export let schema = createSchema({
  type: 'hero-banner',
  title: 'Hero Banner',
  settings: [
    {
      group: 'Content',
      inputs: [
        // ... existing inputs
        {
          type: 'product',
          name: 'product',
          label: 'Featured Product',
        },
      ],
    },
    // ... rest of schema
  ],
});

Performance Optimization

Add caching to your loader:

export async function loader(args: ComponentLoaderArgs<HeroBannerProps>) {
  const { weaverse } = args;
  const { storefront } = weaverse;

  const handle = args.data?.product?.handle;
  if (!handle) {
    return null;
  }

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

  return { product };
}

✨ Pro Tips:

Always cache Shopify API calls for better performance
Use TypeScript for better development experience
Test components with different data states (empty, loading, error)

Part 6: Deployment (5 minutes)

Deploy to Shopify Oxygen

Build your project:
npm run build
Deploy using Shopify CLI:
npx shopify hydrogen deploy
Follow the prompts to connect your Shopify store
Update Weaverse Studio:
- Go to Project Settings
- Update Preview URL to your Oxygen deployment URL
- Save changes

Production Checklist

Before going live, ensure:

Environment variables are set correctly
Images are optimized and loading properly
All sections work as expected
Mobile responsive design looks good
Performance is measured on the deployed site (run Lighthouse and check Core Web Vitals)
SEO metadata is configured

Go Live

Set your Oxygen deployment as your primary domain in Shopify admin
Test thoroughly on the live site
Train your team on using Weaverse Studio

🚀 Congratulations! Your Weaverse Hydrogen store is now live and ready for visual editing.

Next Steps

Expand Your Store

Add More Components:

Product grids with filtering
Customer testimonials
Newsletter signup forms
Collection showcases

Advanced Features:

Multi-language support
B2B customer groups
Advanced search and filtering
Custom checkout experiences

Performance Optimization:

Image optimization strategies
Caching best practices
Core Web Vitals improvements

Learning Resources

Component Development Guide - Deep dive into component creation
Schema Reference - Complete schema options
Styling & Theming - Performance optimization and design patterns
Join our Slack - Get help from the community

Common Issues

Component Not Showing in Studio?

Check component is exported correctly
Verify schema syntax
Ensure component is registered in components.ts

Preview Not Updating?

Check development server is running
Verify Preview URL in Studio settings
Clear browser cache

Deployment Issues?

Ensure all environment variables are set
Check build logs for errors
Verify Shopify app permissions

What You’ve Accomplished

In just 45 minutes, you’ve: ✅ Built a modern Shopify storefront with React Router v7
✅ Created custom components with visual editing capabilities
✅ Connected Shopify data dynamically to your components
✅ Deployed to production on Shopify Oxygen
✅ Set up a workflow for continuous development and content updates Your store is now ready for your team to manage visually through Weaverse Studio, while you focus on building amazing shopping experiences. Ready to build something amazing? Join our Slack community and show us what you create!

Help

Troubleshooting

Community & Updates

Weaverse Tutorial - Build Your First Hydrogen Store

Build Your First Weaverse Hydrogen Store

What You’ll Build

Prerequisites

Part 1: Quick Start (5 minutes)

Install Weaverse Studio

Create Your First Project

Part 2: Local Development Setup (10 minutes)

Set Up Your Development Environment

Connect to Weaverse Studio

Part 3: Understanding Weaverse Architecture (5 minutes)

How Weaverse Works

Key Concepts

Part 4: Build Your First Component (15 minutes)

Create the Component

Register the Component

Test Your Component

Part 5: Advanced Features (10 minutes)

Add Dynamic Product Data

Performance Optimization

Part 6: Deployment (5 minutes)

Deploy to Shopify Oxygen

Production Checklist

Go Live

Next Steps

Expand Your Store

Learning Resources

Common Issues

What You’ve Accomplished

​Build Your First Weaverse Hydrogen Store

​What You’ll Build

​Prerequisites

​Part 1: Quick Start (5 minutes)

​Install Weaverse Studio

​Create Your First Project

​Part 2: Local Development Setup (10 minutes)

​Set Up Your Development Environment

​Connect to Weaverse Studio

​Part 3: Understanding Weaverse Architecture (5 minutes)

​How Weaverse Works

​Key Concepts

​Part 4: Build Your First Component (15 minutes)

​Create the Component

​Register the Component

​Test Your Component

​Part 5: Advanced Features (10 minutes)

​Add Dynamic Product Data

​Performance Optimization

​Part 6: Deployment (5 minutes)

​Deploy to Shopify Oxygen

​Production Checklist

​Go Live

​Next Steps

​Expand Your Store

​Learning Resources

​Common Issues

​What You’ve Accomplished

Build Your First Weaverse Hydrogen Store

What You’ll Build

Prerequisites

Part 1: Quick Start (5 minutes)

Install Weaverse Studio

Create Your First Project

Part 2: Local Development Setup (10 minutes)

Set Up Your Development Environment

Connect to Weaverse Studio

Part 3: Understanding Weaverse Architecture (5 minutes)

How Weaverse Works

Key Concepts

Part 4: Build Your First Component (15 minutes)

Create the Component

Register the Component

Test Your Component

Part 5: Advanced Features (10 minutes)

Add Dynamic Product Data

Performance Optimization

Part 6: Deployment (5 minutes)

Deploy to Shopify Oxygen

Production Checklist

Go Live

Next Steps

Expand Your Store

Learning Resources

Common Issues

What You’ve Accomplished