Skip to content

development.mdx

Latest commit

 

History

History
187 lines (142 loc) · 5.31 KB

development.mdx

File metadata and controls

187 lines (142 loc) · 5.31 KB
title Development
description Complete guide to developing themes and components for Weaverse Hydrogen storefronts

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

Configure your development environment, environment variables, and tools. Learn how to build Weaverse components with proper schemas and TypeScript support. Master the configuration system that lets merchants customize your components. Implement server-side data loading for sections with Shopify API integration.

Quick Start

Get your development environment up and running in minutes:

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
npm install

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

Command line interface for creating and managing themes TypeScript SDKs for building components and integrations AI assistant integration for enhanced development workflow

Troubleshooting

```bash # 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: