​

Installation

🚀 New to Weaverse? Try our 5-Minute Quickstart for the fastest setup experience.

​

Prerequisites

• Node.js 22.12+ - Download here
• A Shopify store - Development store or paid plan
• Basic terminal knowledge - For running commands

​

Installation Methods

​

Method A: Via Weaverse App (Recommended)

1. Install Weaverse App: Visit https://apps.shopify.com/weaverse
2. Create Project: Open app → “Get Started” → Choose theme (Pilot recommended)
3. Run Generated Command: Copy and run the custom CLI command provided

npx @weaverse/cli@latest create --template=pilot --project-id=abc123 --project-name=my-store

cd my-store && npm run dev

​

Method B: Direct CLI Installation

# Create project
npx @weaverse/cli@latest create --template=pilot --project-id=your-project-id --project-name=my-store

# Start development
cd my-store && npm run dev

​

Method C: GitHub Clone

git clone https://github.com/Weaverse/pilot.git my-store
cd my-store && rm -rf .github   # remove Pilot's internal workflows
npm install
cp .env.example .env
# Edit .env with your configuration
npm run dev

​

Configuration

​

Required Environment Variables

# Your Shopify store domain (without https://)
PUBLIC_STORE_DOMAIN=your-store.myshopify.com

# Storefront API token
PUBLIC_STOREFRONT_API_TOKEN=your_storefront_api_token

# Weaverse project ID
WEAVERSE_PROJECT_ID=your-weaverse-project-id

# Session secret
SESSION_SECRET=<generated-random-secret>

​

Getting API Tokens

​

Verification

1. Start server: npm run dev
2. Check storefront: Visit http://localhost:3456
3. Access Studio: Go to https://studio.weaverse.io/projects/your-project-id
4. Test editing: Make changes in Studio and verify they appear

​

Common Issues

​

CLI Command Fails

• Ensure Node.js 22.12+ installed: node --version
• Clear npm cache: npm cache clean --force

​

Studio Preview Not Loading

• Verify dev server runs on port 3456
• Check browser console for errors
• Ensure no firewall blocks the port

​

Environment Variables Not Working

• Ensure .env file is in project root
• Restart dev server after changes
• Check variable names are exact (case-sensitive)

​

Component Development Basics

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

interface HeroProps extends HydrogenComponentProps {
  heading: string;
  description: string;
}

function Hero(props: HeroProps) {
  const { heading, description, className, ...rest } = props;

  return (
    <section {...rest} className={`py-12 px-4 max-w-7xl mx-auto ${className || ''}`}>
      <div className="text-center">
        <h1 className="text-4xl font-bold">{heading}</h1>
        <p className="mt-6 text-lg text-gray-600">{description}</p>
      </div>
    </section>
  );
}

export default Hero;

export const schema = createSchema({
  type: 'hero',
  title: 'Hero Section',
  settings: [
    {
      group: 'Content',
      inputs: [
        { type: 'text', name: 'heading', label: 'Heading', defaultValue: 'Welcome' },
        { type: 'textarea', name: 'description', label: 'Description' },
      ],
    },
  ],
});

​

Development Workflow

1. Create component in app/sections/ or app/components/
2. Define schema with createSchema() and configurable properties
3. Register it in app/weaverse/components.ts by adding the module to the components array:
   // app/weaverse/components.ts
   import type { HydrogenComponent } from '@weaverse/hydrogen';
   import * as Hero from '~/sections/hero';
   
   export const components: HydrogenComponent[] = [Hero];
   
4. Test in Studio at https://studio.weaverse.io/projects/your-project-id

​

Next Steps

1. Core Concepts - Understand how Weaverse works
2. Development Guide - Build custom sections
3. API Reference - Complete API documentation