Skip to main content

​
5-Minute Quickstart

Get your first Weaverse Hydrogen storefront up and running locally in just 5 minutes. No complex setup, no manual configuration – just install the app and start building.

​
What You’ll Build

A complete Shopify Hydrogen storefront powered by Weaverse with:
  • Visual Studio Editor - Drag-and-drop page builder with live preview
  • Professional Theme - Start with Pilot or choose from our theme library
  • Real-time Editing - See changes instantly as you customize
  • Performance Optimized - Modern React, SSR, and edge-ready architecture
  • Merchant-friendly - Anyone can edit content without code

​
Prerequisites

Before starting, make sure you have:
💡 New to terminal? On macOS/Linux open Terminal, on Windows use Command Prompt or PowerShell. You’ll only need to copy and paste a few commands!

​
Step 1: Install Weaverse App

Install from Shopify App Store

  1. Go to Shopify App Store
  2. Install the App
    • Click Add app on the Weaverse Hydrogen listing
    • Review permissions and click Install app
    • The app will be added to your store
The Weaverse app is free to install and includes the visual page builder and theme templates.
Weaverse app in Shopify App Store

​
Step 2: Create Your First Project

Start New Project

  1. Open Weaverse Dashboard
    • In your Shopify admin, go to Apps > Weaverse Hydrogen
    • You’ll see the Weaverse dashboard
  2. Start New Project
    • Click Get Started or Create New Project
    • An onboarding modal will appear
Weaverse dashboard with Get Started button highlighted

​
Step 3: Choose Your Theme

Select a Theme

  1. Available Themes
    • Pilot Theme (recommended for beginners) - Complete e-commerce template with product galleries, hero sections, and testimonials
    • Naturelle Theme - Beauty/lifestyle focused design with elegant layouts
    • Custom themes - Browse additional marketplace options
  2. Theme Selection
    • In the onboarding modal, browse available themes
    • Each theme shows a preview and key features
    • Click on your preferred theme to select it
You can switch themes later, but starting with Pilot is recommended for new users.
Theme selection modal showing Pilot, Naturelle, and other themes

​
Step 4: Quick Setup with CLI

Run the Generated Command

  1. Copy the Generated Command
    • After selecting your theme, you’ll see a custom CLI command
    • This command is unique to your project and includes your Project ID
  2. Example Command: 
npx @weaverse/cli@latest create --template=pilot --project-id=v3gf5xxth6j1u3qr2fa4im1x --project-name=my-hydrogen-storefront
  1. Run in Terminal
    • Open your terminal/command prompt
    • Paste and run the command
    • The setup process will automatically:
      • ✅ Download the selected theme to your local machine
      • ✅ Install all dependencies (React, Hydrogen, etc.)
      • ✅ Update environment variables with your Project ID
      • ✅ Start the development server
Example Terminal Output:
🚀 Downloading Pilot theme...
📦 Installing dependencies...
⚙️  Configuring environment...
🔧 Starting development server...

✅ Your Weaverse storefront is ready!
🌐 Local:    http://localhost:3456
📝 Studio:   https://studio.weaverse.io/projects/your-project-id
CLI command displayed in modal with copy button

​
Step 5: Connect Your Store Data

For Paid Shopify Stores (Recommended)

Hydrogen app installation in Shopify App Store

For Development/Trial Stores

  1. Create Storefront API Token
    • In Shopify Admin, go to Apps > Develop apps
    • Click Create an app
    • Name it “Weaverse Storefront”
    • Alternative: Use the Headless app (https://apps.shopify.com/headless) for easier setup
    • Configure Storefront API scopes and enable all permissions
  2. Update Environment Variables 
    # Edit your .env file with:
PUBLIC_STORE_DOMAIN=your-store.myshopify.com
PUBLIC_STOREFRONT_API_TOKEN=your_generated_token
  3. Restart Development Server 
    npm run dev
Creating Storefront API token in Shopify admin
Weaverse Studio interface with localhost:3456 loaded in preview

​
Step 6: Customize Your Storefront

Now for the fun part! Start customizing your storefront in Weaverse Studio:

Visual Editing

Drag & Drop Sections
  • Add new sections from the left panel
  • Rearrange sections by dragging
  • Remove sections you don’t need
Edit Content
  • Click on any text to edit inline
  • Upload your own images through the media manager
  • Adjust colors, fonts, and spacing using the settings panel
Preview Changes
  • See changes instantly in the preview iframe
  • Test on different device sizes with responsive toggles
  • Use the mobile/tablet/desktop preview modes
Studio with section being dragged, text being edited, and device preview toggles

Brand Customization

Update Your Brand
  • Replace the default logo with your brand logo
  • Update the color scheme to match your brand
  • Customize fonts and typography
  • Add your brand messaging to hero sections
Content Updates
  • Update product collections and featured items
  • Customize navigation menus
  • Add your social media links
  • Update contact information and policies

​
Verify Everything Works

🎉 Congratulations! Let’s make sure everything is working perfectly:

​
✅ Checklist

  • Storefront loads at http://localhost:3456
  • Your real products and collections appear
  • Navigation menus show your store structure
  • Search finds your actual products
  • Cart and checkout process work
  • Weaverse Studio loads at https://studio.weaverse.io/projects/your-project-id
  • You can edit content and see changes instantly

​
🔍 Test Your Store

  1. Browse Products: Check that your actual products load with correct images and prices
  2. Add to Cart: Test the shopping cart functionality
  3. Mobile View: Use browser dev tools to test mobile responsiveness
  4. Studio Editing: Make a change in Studio and verify it appears immediately
Live storefront showing real products with Weaverse Studio editing panel

​
What’s Next?

🎉 Your storefront is live! Now it’s time to customize and extend it. Choose your path:

​
For Developers

Create Custom Components

Build reusable React components with Weaverse’s schema system

Component Schema Guide

Define component structure, settings, and behavior

Data Fetching

Fetch Shopify data and external APIs in your components

API Reference

Complete docs for hooks, components, utilities, and types

​
For Visual Builders

Studio Interface Tour

Master the visual editor and all its tools

Global Sections

Create reusable headers, footers, and content blocks

Navigation Menus

Build custom navigation with Shopify menu integration

Markets & Localization

Support multiple languages and international markets

​
Deploy Your Store

Deploy to Oxygen

Shopify’s edge hosting platform (recommended)

Deploy with Docker

Self-hosted containerized deployment

Other Platforms

Vercel, Netlify, Fly.io, and custom hosting

Migration Guide

Migrate from existing Hydrogen or Liquid themes

​
Learning Resources

Example Components

Browse ready-to-use component examples

FAQ

Answers to common questions

Video Tutorials

Step-by-step video guides

​
Get Help

Community Slack

Join 500+ developers and merchants in our Slack community

Troubleshooting

Common issues and solutions
Pro Tip: Start by customizing your homepage in Studio, then gradually explore component development as you become more comfortable with the platform. Remember, you don’t need to code to use Weaverse - the visual editor handles everything!