quickstart.mdx

title	5-Minute Quickstart
description	Get a Weaverse Hydrogen storefront running locally in just 5 minutes

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:

• Node.js 18+ - Download here and verify with node --version
• A Shopify store - Create a development store (free for testing)
• Basic terminal knowledge - Copy/paste commands (we'll guide you!)

💡 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

1. **Go to Shopify App Store** - Open your Shopify admin panel - Navigate to **Apps** in the sidebar - Search for "Weaverse Hydrogen" or visit [Weaverse on Shopify App Store](https://apps.shopify.com/weaverse)

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

<Tip>The Weaverse app is free to install and includes the visual page builder and theme templates.</Tip>

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. **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

<Note>You can switch themes later, but starting with Pilot is recommended for new users.</Note>

Step 4: Quick Setup with CLI

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:**
```bash
npx @weaverse/cli@latest create --template=pilot --project-id=v3gf5xxth6j1u3qr2fa4im1x --project-name=my-hydrogen-storefront
```

3. **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:**
```bash
🚀 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
```

Step 5: Connect Your Store Data

1. **Install Hydrogen App** - Go to https://apps.shopify.com/hydrogen - Install the **Hydrogen** app (by Shopify) - This creates a Hydrogen sales channel

2. **Pull Store Environment**
   ```bash
   # Make sure you're in your theme folder
   cd my-hydrogen-storefront
   
   # Pull your store's environment variables
   npx shopify hydrogen env pull
   ```

3. **Follow CLI Prompts**
   - Select your Shopify store
   - Choose your Hydrogen project
   - The CLI will automatically update your `.env` file

 4. **Restart Development Server**
    ```bash
    npm run dev
    ```

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**
   ```bash
   # Edit your .env file with:
   PUBLIC_STORE_DOMAIN=your-store.myshopify.com
   PUBLIC_STOREFRONT_API_TOKEN=your_generated_token
   ```

 3. **Restart Development Server**
    ```bash
    npm run dev
    ```

Step 6: Customize Your Storefront

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

**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

**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

What's Next?

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

For Developers

Build reusable React components with Weaverse's schema system Define component structure, settings, and behavior Fetch Shopify data and external APIs in your components Complete docs for hooks, components, utilities, and types

For Visual Builders

Master the visual editor and all its tools Create reusable headers, footers, and content blocks Build custom navigation with Shopify menu integration Support multiple languages and international markets

Deploy Your Store

Shopify's edge hosting platform (recommended) Self-hosted containerized deployment Vercel, Netlify, Fly.io, and custom hosting Migrate from existing Hydrogen or Liquid themes

Learning Resources

Browse ready-to-use component examples Answers to common questions Step-by-step video guides

Get Help

Join 500+ developers and merchants in our Slack community 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!