Skip to main content

​
Development Guide

This comprehensive guide covers everything you need to know to develop themes and components for Weaverse Hydrogen storefronts.

​
Prerequisites

Before you start developing with Weaverse, ensure you have:
  • Node.js 18+ installed
  • Familiarity with React and TypeScript
  • Basic knowledge of Shopify Hydrogen
  • Understanding of Tailwind CSS (recommended)

​
Development Workflow

Environment Setup

Configure your development environment, environment variables, and tools.

Creating Components

Learn how to build Weaverse components with proper schemas and TypeScript support.

Input Settings

Master the configuration system that lets merchants customize your components.

Data Fetching

Implement server-side data loading for sections with Shopify API integration.

​
Quick Start

Get your development environment up and running in minutes:
1

Clone or Create Project

Use the Weaverse CLI to create a new theme:
npx @weaverse/cli@latest create --template=pilot --project-id=your-project-id
Or clone an existing theme repository:
git clone your-theme-repository
cd your-theme-directory
2

Install Dependencies

npm install
3

Configure Environment

Create a .env file with your Weaverse and Shopify credentials:
# Core Variables
SESSION_SECRET="your-session-secret"
PUBLIC_STORE_DOMAIN="your-store.myshopify.com"
PUBLIC_STOREFRONT_API_TOKEN="your-storefront-api-token"
WEAVERSE_PROJECT_ID="your-weaverse-project-id"

# Optional: Use demo data during development
# PUBLIC_STORE_DOMAIN="mock.shop"
4

Start Development Server

npm run dev
Your storefront will be available at http://localhost:3456

​
Development Commands

​
Core Development

npm run dev          # Start development server
npm run dev:ca       # Start dev server with Customer Account API (via CF tunnel)
npm run build        # Production build
npm run start        # Start production server
npm run preview      # Build and start production

​
Code Quality

npm run typecheck    # TypeScript checking
npm run biome        # Check code quality with Biome
npm run biome:fix    # Fix code quality issues automatically
npm run format       # Format code with Biome
npm run format:check # Check formatting without changes

​
Testing

npm run e2e          # Run end-to-end tests with Playwright
npm run e2e:ui       # Run E2E tests with Playwright UI

​
Quick Start Checklist

  • Set up your development environment
  • Create your first component with schema
  • Add input settings for customization
  • Test in Weaverse Studio
  • Implement proper TypeScript types
  • Add error boundaries and loading states

​
Best Practices

  • Performance: Keep components lightweight and optimize images
  • Accessibility: Follow WCAG guidelines and use semantic HTML
  • Mobile-First: Design responsive components from the start
  • Schema Design: Create intuitive settings that merchants will understand
  • Error Handling: Gracefully handle missing data and API failures

​
Development Tools

Weaverse CLI

Command line interface for creating and managing themes

Weaverse SDKs

TypeScript SDKs for building components and integrations

Weaverse MCP

AI assistant integration for enhanced development workflow

​
Troubleshooting

# 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
  • 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
  • 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

​
Next Steps

Once you’ve mastered the basics:
⌘I