> ## Documentation Index
> Fetch the complete documentation index at: https://weaverse.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 5-Minute Quickstart
> 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 22.12+** - [Download here](https://nodejs.org/) and verify with `node --version`
* **A Shopify store** - [Create a development store](https://partners.shopify.com/) (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](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)
The fastest way to get going is to let your AI coding agent do the setup. The onboarding modal gives you a ready-to-paste prompt tailored to your project.
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`](/docs/developer-tools/shopify-hydrogen-skills) 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
**Why demo-first?** You get a working storefront immediately, then swap in your own store data once you've seen it run. No Shopify tokens, GitHub setup, or manual secrets before the win. See Step 7 to connect your real store.
The modal also includes a CLI command as a backup. Copy the command from your project modal, or use this pattern and replace the placeholders:
```bash theme={null}
npx @weaverse/cli@latest create --template=pilot --project-id=YOUR_PROJECT_ID --project-name=my-hydrogen-storefront
```
Use the Project ID shown in your Weaverse onboarding modal or in **Project Settings** inside Weaverse Studio.
The command is unique to your project and includes your Project ID. It downloads the selected theme, creates the local environment file, and installs dependencies.
In an interactive terminal, the CLI asks whether to start the development server. In a non-interactive run, it starts the server only when the command includes `--dev`. Use an explicit next step for deterministic setup:
```bash theme={null}
cd my-hydrogen-storefront
npm run dev
```
When the server is ready, open `http://localhost:3456`. Connect Studio at `https://studio.weaverse.io/projects/YOUR_PROJECT_ID`.
***
## 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
Now for the fun part! Start customizing 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
Right now you're seeing demo content. Let's connect your actual store data:
### Option A: Stores on a Shopify plan (Recommended)
1. **Install Hydrogen Sales Channel**
* Go to [https://apps.shopify.com/hydrogen](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**
```bash theme={null}
# 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
If `env pull` is not available or the project is not linked yet, copy the values manually from **Shopify Admin → Hydrogen sales channel → Storefront Settings → Environments and variables**, then add them to `.env`.
5. **Restart Development Server**
```bash theme={null}
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](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`
```bash theme={null}
# 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**
```bash theme={null}
npm run dev
```
***
## Step 8: Verify Everything Works
Before moving on, make sure the local storefront and Studio preview are working together:
### 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
**Problem**: The generated CLI command fails to run
**Solutions**:
* 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
**Problem**: Weaverse Studio shows a blank preview or connection error
**Solutions**:
* 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
**Problem**: Still seeing demo products instead of your store data
**Solutions**:
* 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
```bash theme={null}
# 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
```bash theme={null}
# Kill any process using port 3456
npx kill-port 3456
# Or start on a different port
npm run dev -- --port 3457
```
*Note: If you change the port, update the Preview URL in Weaverse Studio accordingly*
### Environment Variables Not Working
**Problem**: Store data or Weaverse features not working
**Solutions**:
* 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?
🎉 **You're ready to build!** Here's your roadmap to mastering Weaverse:
### 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](/docs/hydrogen-themes)** - Browse available themes and components
2. **[Core Concepts](/docs/core-concepts)** - Understand how Weaverse works
3. **[Features](/docs/features)** - Configure meta tags and integrations
### Medium Term (Next Month)
1. **[Custom Components](/docs/development-guide/index)** - Build sections unique to your brand
2. **[API Reference](/docs/api-reference/introduction)** - Learn advanced customization options
3. **[Deployment](/docs/guides/deployment)** - Set up production hosting
### Production Launch
When you're ready to go live:
* **[Deployment Guide](/docs/guides/deployment)** - Choose your hosting platform
* **[Security](/docs/features/content-security)** - Configure SSL and security headers
## Need Help?
* 🚀 **[Complete Tutorial](/docs/resources/tutorial)** - Deep dive walkthrough
* 💬 **[Community](/docs/community/community)** - Connect with other merchants and developers
* 📚 **[FAQ](/docs/resources/faq)** - Common questions answered
***
## Success
You've just created a modern, high-performance e-commerce storefront in under 10 minutes. Here's what makes your setup special:
* ✅ **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
**Time to live storefront**: Under 10 minutes
Ready to customize and launch? Dive into [Core Concepts](/docs/core-concepts) to understand how everything works together!
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.