​

5-Minute Quickstart

​

What You’ll Build

• 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

• Node.js 22.12+ - Download here and verify with node --version
• A Shopify store - Create a development store (free for testing)
• An AI coding agent (recommended) - Cursor, Claude Code, Codex, Windsurf, or similar. The agent handles setup for you so you barely touch the terminal.

💡 No coding agent? You can still follow along with the CLI fallback in Step 4 — you’ll only need to copy and paste a few commands. On macOS/Linux open Terminal, on Windows use Command Prompt or PowerShell.

​

Step 1: Install Weaverse App

1. Go to Shopify App Store
   • Open your Shopify admin panel
   • Navigate to Apps in the sidebar
   • Search for “Weaverse Hydrogen Page Builder” or visit https://apps.shopify.com/weaverse
2. Install the App
   • Click Add app on the Weaverse Hydrogen Page Builder listing
   • Review permissions and click Install app
   • The app will be added to your store

​

Step 2: Create Your First 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

​

Step 3: Choose Your Theme

1. Select a Theme
   • In the onboarding modal, browse available themes
   • Pilot Theme (recommended for beginners) - Complete e-commerce template
   • Naturelle Theme - Beauty/lifestyle focused design
   • Custom themes - Explore marketplace options
2. Preview Theme Features
   • Each theme shows a preview and key features
   • Click on your preferred theme to select it

​

Step 4: Set Up with Your AI Agent (Recommended)

1. Copy the AI Agent Prompt
   • After selecting your theme, the modal shows an AI agent prompt as the primary option
   • It already includes your WEAVERSE_PROJECT_ID and theme
2. Paste It Into Your Agent
   • Works with Cursor, Claude Code, Codex, Windsurf, Gemini CLI, and others
   • The agent loads the setup-weaverse-project skill and runs the full setup
3. What the Agent Does
   • Runs the Weaverse CLI to scaffold your selected theme and makes it your own fresh git repo
   • Boots a live preview on a demo store first — you see your storefront running at http://localhost:3456 in ~2 minutes, before you have to provide any credentials
   • Generates local-only values like SESSION_SECRET automatically
   • Then helps you make it yours: your Shopify store env, a new GitHub repo, and connecting the preview back to Weaverse Studio
   • Verifies everything works before telling you it’s done

npx @weaverse/cli@latest create --template=pilot --project-id=YOUR_PROJECT_ID --project-name=my-hydrogen-storefront

cd my-hydrogen-storefront
npm run dev

​

Step 5: Create Project & Load Studio

1. Complete Project Creation
   • Back in the Weaverse modal, click Create Project
   • The project will be created in your Weaverse dashboard
2. Studio Loads Automatically
   • Weaverse Studio will open at https://studio.weaverse.io/projects/YOUR_PROJECT_ID
   • You’ll see your theme loaded with http://localhost:3456 in the preview
   • The content will initially come from demo data

​

Step 6: Customize Your Storefront

1. Drag & Drop Sections
   • Add new sections from the left panel
   • Rearrange sections by dragging
   • Remove sections you don’t need
2. Edit Content
   • Click on any text to edit inline
   • Upload your own images
   • Adjust colors, fonts, and spacing
3. Preview Changes
   • See changes instantly in the preview
   • Test on different device sizes
   • Use the mobile/tablet/desktop toggles

​

Step 7: Connect Your Real Store Data

​

Option A: Stores on a Shopify plan (Recommended)

1. Install Hydrogen Sales Channel
   • Go to https://apps.shopify.com/hydrogen
   • Install the Hydrogen app (by Shopify)
   • This creates a Hydrogen sales channel
2. Create a Hydrogen Storefront Project
   • Open the Hydrogen sales channel in Shopify Admin
   • Create one Hydrogen storefront project for this store
3. Pull Store Environment
   # Make sure you're in your theme folder
   cd my-hydrogen-storefront
   
   # Pull your store's environment variables
   npx shopify hydrogen env pull
   
4. Follow CLI Prompts
   • Select your Shopify store. If an AI agent is driving the CLI and more than one shop appears, give it the exact .myshopify.com domain to select.
   • Choose the Hydrogen storefront project you created
   • The CLI will automatically update your .env file

5. Restart Development Server
   npm run dev
   

​

Option B: Development stores or stores without a Shopify plan

1. Install Headless Sales Channel
   • Go to https://apps.shopify.com/headless
   • Install the Headless app (by Shopify)
   • Create or open a storefront inside the Headless channel
2. Update Environment Variables
   • Copy the Storefront API values from the Headless channel
   • Add them to .env, or give them to your AI agent and let it update .env
   # Edit your .env file with:
   PUBLIC_STORE_DOMAIN=your-store.myshopify.com
   PUBLIC_STOREFRONT_API_TOKEN=your_generated_token
   
   You do not need to create SESSION_SECRET manually. The Weaverse CLI and agent setup generate it for you.
3. Restart Development Server
   npm run dev
   

​

Step 8: Verify Everything Works

​

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

​

Troubleshooting

​

CLI Command Not Working

• Ensure Node.js 22.12+ is installed: node --version
• Check internet connection for downloading packages
• Copy the latest command directly from the Weaverse onboarding modal
• Confirm you replaced YOUR_PROJECT_ID with your actual Project ID
• Clear npm cache: npm cache clean --force

​

Studio Preview Not Loading

• Verify development server is running on port 3456
• Check that http://localhost:3456 loads in your browser
• Ensure no firewall is blocking port 3456
• Try refreshing the Studio page

​

Demo Data Still Showing

• Make sure you completed Step 7 (Connect Real Store Data)
• Verify your .env file has correct store domain and API token
• Restart the development server: Ctrl+C then npm run dev
• Check Shopify store has products published to “Online Store” sales channel

​

”Module not found” Errors

# If packages failed to install properly
cd my-hydrogen-storefront
rm -rf node_modules package-lock.json  
npm install
npm run dev

​

Port 3456 Already in Use

# Kill any process using port 3456
npx kill-port 3456

# Or start on a different port
npm run dev -- --port 3457

​

Environment Variables Not Working

• Ensure .env file is in the project root (same level as package.json)
• Check variable names are exactly correct (case-sensitive)
• Restart development server after any .env changes
• Verify no spaces around the = sign in environment variables

​

What’s Next?

​

Immediate Actions (Next 15 minutes)

1. Customize Your Brand
   • Replace the logo with your brand
   • Update colors to match your brand palette
   • Edit the hero section with your messaging
2. Add Your Content
   • Upload product images
   • Write compelling product descriptions
   • Create your About Us page
3. Test Everything
   • Browse on mobile and desktop
   • Test the cart and checkout process
   • Share with team members for feedback

​

Short Term Goals (This Week)

1. Explore Themes - Browse available themes and components
2. Core Concepts - Understand how Weaverse works
3. Features - Configure meta tags and integrations

​

Medium Term (Next Month)

1. Custom Components - Build sections unique to your brand
2. API Reference - Learn advanced customization options
3. Deployment - Set up production hosting

​

Production Launch

• Deployment Guide - Choose your hosting platform
• Security - Configure SSL and security headers

​

Need Help?

• 🚀 Complete Tutorial - Deep dive walkthrough
• 💬 Community - Connect with other merchants and developers
• 📚 FAQ - Common questions answered

​

Success

• ✅ Lightning Fast - Hydrogen’s SSR and edge deployment
• ✅ Visual Editing - Anyone on your team can update content
• ✅ Mobile Optimized - Perfect on every device
• ✅ SEO Ready - Built for search engine success
• ✅ Developer Friendly - Full React component control when needed

​

Your Storefront Features

• Professional Theme - Pilot theme with proven conversion patterns
• Visual Editing - Drag-and-drop customization in Weaverse Studio
• Mobile First - Responsive design out of the box
• Performance - Sub-second load times
• Complete E-commerce - Cart, checkout, and payment ready