{title}
} {description &&{description}
}...
;
}
```
**React DevTools**: Full support for component inspection
**Studio Debugging**:
* Check browser console for Studio connection issues
* Inspect WebSocket messages in Network tab
* Use Studio's component inspector
**Production Debugging**:
* Source maps enabled in development builds
* Performance profiling with React DevTools
* Error boundaries for graceful failure handling
### Can I use custom CSS/Sass/CSS-in-JS?
**Tailwind CSS** (recommended):
```typescript theme={null}
```
**Custom CSS**:
```typescript theme={null}
// Import in component
import './styles.css';
```
**CSS-in-JS**:
```typescript theme={null}
import styled from 'styled-components';
const StyledComponent = styled.div`
background: blue;
padding: 1rem;
`;
```
**Sass/SCSS**: Full support via Vite configuration
### How do I handle responsive design?
**Tailwind Responsive Classes**:
```typescript theme={null}
```
**CSS Custom Properties**:
```typescript theme={null}
const style = {
'--mobile-size': '1rem',
'--desktop-size': '1.5rem',
} as CSSProperties;
Responsive heading
```
**Schema Configuration**:
```typescript theme={null}
{
type: 'range',
name: 'mobileSize',
label: 'Mobile Size',
}
```
### What testing strategies work with Weaverse?
**Unit Testing**:
```typescript theme={null}
// With Vitest
import { render, screen } from '@testing-library/react';
import MyComponent from './my-component';
test('renders component correctly', () => {
render(
// ✅ Correct - optimized Weaverse images
(null);
useEffect(() => {
setTimestamp(Date.now()); // Set after hydration
}, []);
return
...
;
}
// Weaverse-enabled version
const ProductCard = forwardRef((props, ref) => {
return ...
;
});
export let schema = createSchema({
type: 'product-card',
// Add schema configuration
});
```
**Key Changes**:
* Add Weaverse schema exports
* Implement forwardRef patterns
* Update component registration
* Add Studio configuration
### What happens to my metafields and custom data?
**Full Compatibility**: Weaverse maintains complete compatibility with Shopify metafields:
**Metafield Access**:
```typescript theme={null}
// In component loaders
export const loader = async ({ weaverse }) => {
const { storefront } = weaverse;
const product = await storefront.query(PRODUCT_QUERY, {
variables: { handle: 'product-handle' }
});
// Access metafields normally
const customData = product.metafields;
return { product, customData };
};
```
**Custom Data Integration**:
* Product metafields: Full access
* Collection metafields: Complete support
* Customer metafields: Available in customer routes
* Store metafields: Global access via settings
### Can I run Weaverse and traditional themes simultaneously?
**Hybrid Approach**: Yes, with proper configuration:
**Use Cases**:
* Gradual migration strategy
* A/B testing new vs. old
* Feature-specific implementations
* Risk mitigation during transition
**Implementation**:
1. Deploy Weaverse on subdomain (shop-new\.example.com)
2. Use URL-based routing for specific pages
3. Gradually migrate sections of the site
4. Maintain both themes during transition
**Considerations**:
* SEO implications of split traffic
* Analytics tracking setup
* Customer experience consistency
* Maintenance overhead
### How do I handle URL redirects?
**Built-in Redirect Handling**:
```typescript theme={null}
// In route loaders
export const loader = ({ request }) => {
const url = new URL(request.url);
// Handle legacy URLs
if (url.pathname.startsWith('/old-path/')) {
throw redirect('/new-path/' + url.pathname.slice(11));
}
};
```
**Redirect Configuration (Shopify Oxygen/Cloudflare Workers)**:
```typescript theme={null}
// Handle redirects in your React Router loader
export async function loader({ request, params }) {
const url = new URL(request.url);
// Legacy URL redirects
if (url.pathname.startsWith('/old-path/')) {
return redirect(url.pathname.replace('/old-path/', '/new-path/'), 301);
}
// Product handle redirects
if (params.handle === 'old-product-handle') {
return redirect('/products/new-product-handle', 301);
}
// Continue with normal loading...
}
```
**Migration Strategy**:
1. Document all current URLs
2. Map old URLs to new structure
3. Implement redirect rules
4. Test redirect chains
5. Monitor 404 errors post-migration
### Is Weaverse compatible with Shopify's checkout extensibility?
**Full Compatibility**: ✅ Weaverse works seamlessly with Shopify's modern checkout:
**Checkout Extensions**:
* Payment customizations
* Shipping method modifications
* Order summary enhancements
* Custom validation rules
**Implementation**:
```typescript theme={null}
// Checkout extension integration
const checkoutUrl = await storefront.checkoutURL({
lineItems: cartItems,
extensions: {
'checkout-ui-extension': extensionData
}
});
```
**Features Supported**:
* Shopify Functions integration
* Custom checkout fields
* Third-party payment providers
* Post-purchase extensions
### Can I migrate content from other page builders?
**Professional Migration Service**: Contact our Weaverse team for assistance migrating from any platform to Weaverse Hydrogen.
**We Handle Migrations From**:
* ✅ **Shopify Page Builders**: PageFly, Shogun, GemPages, etc.
* ✅ **WordPress**: Elementor, Gutenberg, WooCommerce sites
* ✅ **Other Platforms**: Webflow, Squarespace, Magento, custom builds
* ✅ **Legacy Shopify**: Online Store 2.0, older Liquid themes
* ✅ **Existing Hydrogen**: Convert any Hydrogen project to use Weaverse
**What's Included**:
* Complete content and layout migration
* Component recreation and optimization
* SEO preservation and enhancement
* Training on Weaverse workflow
* Post-migration support
**Get Started**: Join our [Slack community](https://wvse.cc/weaverse-slack) or contact support to discuss your migration needs.
### What about existing Shopify Plus customizations?
**Full Plus Support**: All Shopify Plus features remain functional:
**Plus Features**:
* ✅ Shopify Scripts (Discount/Payment/Shipping)
* ✅ Flow automation integration
* ✅ B2B wholesale functionality
* ✅ Multi-market and internationalization
* ✅ Advanced analytics and reporting
* ✅ Custom checkout processes
**Script Integration**:
```typescript theme={null}
// Shopify Scripts remain functional
// Hydrogen cart integrates with Plus features
const { cart } = await storefront.cartQuery({
// Plus-specific configurations work normally
});
```
**Advanced Plus Workflows**:
* Bulk order management
* Custom pricing rules
* Inventory management integration
* Advanced customer segmentation
***
## Shopify Integration
### Which Shopify APIs does Weaverse use?
**Primary APIs**:
* **Storefront API**: Product data, cart operations, customer data
* **Admin API**: Store configuration, webhook management (when needed)
* **Webhooks**: Real-time updates for product/inventory changes
* **GraphQL**: Primary query language for all API interactions
**API Usage Patterns**:
```typescript theme={null}
// Storefront API usage
const { products } = await storefront.query(PRODUCTS_QUERY, {
variables: { first: 20, query: 'available:true' }
});
// Webhook integration
export const webhookHandler = async (topic, shop, body) => {
// Handle product updates, order notifications, etc.
};
```
**Rate Limiting**: Built-in handling with exponential backoff and caching strategies.
### Can I use Shopify apps with Weaverse?
**App Compatibility**: Most Shopify apps work seamlessly:
**Fully Compatible**:
* ✅ Payment apps (PayPal, Stripe, etc.)
* ✅ Shipping apps (ShipStation, Easyship)
* ✅ Marketing apps (Klaviyo, Mailchimp)
* ✅ Analytics apps (Google Analytics, Hotjar)
* ✅ Review apps (Yotpo, Judge.me)
**Integration Required**:
* 🔧 Theme-dependent apps (may need component recreation)
* 🔧 Liquid-based apps (require React conversion)
* 🔧 Checkout apps (use Shopify Functions instead)
**Implementation Example**:
```typescript theme={null}
// Integrating review app
const ProductReviews = ({ productId }) => {
const reviews = useReviews(productId); // Custom hook for app API
return
{subscriptionPlans.map(plan => (
);
};
```
**Popular Subscription Apps**:
* ReCharge (full integration support)
* Bold Subscriptions (React components available)
* Shopify Subscriptions (native support)
**Implementation Features**:
* Subscription plan selection
* Billing frequency options
* Pause/skip functionality
* Customer portal integration
### What about Shopify Functions?
**Full Functions Support**: ✅
**Function Types**:
* ✅ Discount functions
* ✅ Shipping customization
* ✅ Payment customization
* ✅ Cart validation
* ✅ Fulfillment constraints
**Implementation Example**:
```typescript theme={null}
// Discount function integration
export const applyDiscount = async (cart) => {
const discountAmount = await callShopifyFunction(
'discount-function-id',
{ cart: cart.data }
);
return discountAmount;
};
```
**Development Workflow**:
* Functions developed separately from theme
* Integration via GraphQL API calls
* Testing in development stores
* Deployment via Shopify CLI
***
## Deployment & DevOps
### Where can I deploy?
**Supported Deployment Options**:
**Shopify Oxygen** (Primary & Recommended):
```bash theme={null}
# Deploy to Oxygen
npx shopify hydrogen deploy
```
* ✅ **Full Weaverse Support**: Complete integration with Weaverse Studio
* ✅ **Native Shopify Integration**: Seamless Shopify API access
* ✅ **Cloudflare Workers**: Global edge network (200+ data centers)
* ✅ **Zero Configuration**: Deploy directly from Shopify CLI
* ✅ **Automatic Scaling**: Handle traffic spikes automatically
**Recommendation**: Use Shopify Oxygen for all production deployments to ensure full Weaverse functionality.
### How do I set up staging environments?
**Multi-Environment Setup**:
**1. Environment Configuration**:
```bash theme={null}
# Production .env
PUBLIC_STORE_DOMAIN=production-store.myshopify.com
PUBLIC_STOREFRONT_API_TOKEN=prod_token
WEAVERSE_PROJECT_ID=prod_project_id
# Staging .env.staging
PUBLIC_STORE_DOMAIN=staging-store.myshopify.com
PUBLIC_STOREFRONT_API_TOKEN=staging_token
WEAVERSE_PROJECT_ID=staging_project_id
```
**2. Deployment Pipeline**:
```yaml theme={null}
# GitHub Actions example for Shopify Oxygen
name: Deploy to Staging
on:
push:
branches: [staging]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Deploy to Shopify Oxygen Staging
run: |
npm ci
npm run build
npx shopify hydrogen deploy --environment staging
env:
SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN: ${{ secrets.STAGING_SHOPIFY_TOKEN }}
```
**3. Branch Strategy**:
* `main` → Production
* `staging` → Staging environment
* `feature/*` → Preview deployments
* `develop` → Development environment
### How do I set up CI/CD pipelines?
**GitHub Actions Example**:
```yaml theme={null}
name: CI/CD Pipeline
on:
push:
branches: [main, staging]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '22'
cache: 'npm'
- run: npm ci
- run: npm run typecheck
- run: npm run test:run
- run: npm run build
deploy:
needs: test
runs-on: ubuntu-latest
if: github.ref == 'refs/heads/main'
steps:
- uses: actions/checkout@v3
- name: Deploy to Production
run: |
npm ci
npm run build
npx shopify hydrogen deploy
env:
SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN: ${{ secrets.SHOPIFY_TOKEN }}
```
**Pipeline Features**:
* Automated testing
* Type checking
* Build verification
* Preview deployments
* Production deployment
* Rollback capabilities
**Container Features**:
* Multi-stage builds
* Optimized image size
* Security scanning
* Health check endpoints
* Horizontal scaling
* Load balancer integration
### How do I handle environment variables?
**Environment Configuration**:
**Development (.env.local)**:
```bash theme={null}
# Shopify Configuration
PUBLIC_STORE_DOMAIN=dev-store.myshopify.com
PUBLIC_STOREFRONT_API_TOKEN=dev_storefront_token
SESSION_SECRET=dev_session_secret
# Weaverse Configuration
WEAVERSE_PROJECT_ID=dev_project_id
# Optional Services
GOOGLE_ANALYTICS_ID=GA-DEV-ID
KLAVIYO_API_KEY=dev_klaviyo_key
```
**Production Security**:
* Use platform secret management
* Rotate secrets regularly
* Limit access permissions
* Audit secret usage
* Monitor for leaks
**Shopify Oxygen**:
```bash theme={null}
# Set environment variables in Shopify CLI
shopify hydrogen env set SECRET_NAME "secret-value" --environment production
```
### How do I monitor production performance?
**Performance Monitoring**:
**1. Built-in Analytics**:
* Shopify Analytics (built into Oxygen)
* Core Web Vitals reporting
* Oxygen performance metrics
* Edge cache analytics
**2. Third-party Solutions**:
```typescript theme={null}
// Sentry error tracking
import * as Sentry from '@sentry/react';
Sentry.init({
dsn: process.env.SENTRY_DSN,
integrations: [new Sentry.BrowserTracing()],
tracesSampleRate: 1.0,
});
// DataDog APM
import { datadogRum } from '@datadog/browser-rum';
datadogRum.init({
applicationId: process.env.DD_APPLICATION_ID,
clientToken: process.env.DD_CLIENT_TOKEN,
});
```
**Metrics to Track**:
* Core Web Vitals (LCP, FID, CLS)
* Error rates and types
* API response times
* Conversion funnel metrics
* User session recordings
**Alerting Setup**:
* Performance degradation alerts
* Error rate thresholds
* Uptime monitoring
* Security incident notifications
***
## Troubleshooting
### Components not showing in Studio
**Common Causes & Solutions**:
**1. Component Registration Issues**:
```typescript theme={null}
// ❌ Incorrect - component not exported properly
export MyComponent;
// ✅ Correct - proper component export
export default MyComponent;
export let schema = createSchema({...});
```
```typescript theme={null}
// ❌ Incorrect - missing from components array
export const components = [
// MyComponent missing here
];
// ✅ Correct - component included
export const components = [
* as MyComponent,
];
```
**2. Schema Validation Errors**:
```typescript theme={null}
// ❌ Incorrect - invalid schema structure
export let schema = {
type: 'my-component', // Missing createSchema wrapper
};
// ✅ Correct - proper schema validation
export let schema = createSchema({
type: 'my-component',
title: 'My Component'
});
```
**3. TypeScript Compilation Errors**:
* Check browser console for TypeScript errors
* Run `npm run typecheck` to identify issues
* Ensure all imports resolve correctly
* Verify props interface matches component usage
**Debugging Steps**:
1. Check browser console for errors
2. Verify component appears in network requests
3. Test component registration with `console.log`
4. Validate schema with createSchema function
5. Restart development server
### Build errors and TypeScript issues
**Common Build Errors**:
**1. TypeScript Configuration Issues**:
```bash theme={null}
# Error: Cannot find module '@weaverse/hydrogen'
npm install @weaverse/hydrogen @weaverse/react @weaverse/core
# Error: Type definitions missing
npm run typecheck # Identify specific type issues
```
**2. Import Resolution Problems**:
```typescript theme={null}
// ❌ Incorrect - wrong import path
import { createSchema } from 'weaverse';
// ✅ Correct - proper import path
import { createSchema } from '@weaverse/hydrogen';
```
**3. React Router v7 Type Issues**:
```typescript theme={null}
// ❌ Incorrect - old Remix imports
import type { LoaderArgs } from '@remix-run/node';
// ✅ Correct - React Router v7 types
import type { Route } from './+types/route-name';
export const loader = ({ params }: Route.LoaderArgs) => {};
```
**Resolution Steps**:
1. Clear all caches: `rm -rf node_modules .react-router dist`
2. Reinstall dependencies: `npm install`
3. Generate types: `npx react-router typegen`
4. Check for version conflicts: `npm ls`
5. Update TypeScript configuration if needed
### Studio not loading/connecting
**Connection Issues**:
**1. Development Server Problems**:
```bash theme={null}
# Verify dev server is running
npm run dev # Should start both studio and remix servers
# Check port availability
lsof -i :3456 # Weaverse default port
netstat -an | grep :3456
```
**2. CORS Configuration**:
```typescript theme={null}
// vite.config.ts - Add CORS headers if needed
export default defineConfig({
server: {
cors: {
origin: 'https://studio.weaverse.io',
credentials: true
}
}
});
```
**3. Environment Variable Issues**:
```bash theme={null}
# Verify required environment variables
echo $WEAVERSE_PROJECT_ID
echo $PUBLIC_STORE_DOMAIN
echo $PUBLIC_STOREFRONT_API_TOKEN
# Check .env file exists and is properly formatted
cat .env
```
**4. Browser/Network Issues**:
* Clear browser cache and cookies
* Disable ad blockers/extensions
* Check firewall settings
* Try incognito/private browsing mode
* Verify internet connectivity
**Debugging Tools**:
* Browser Developer Tools (Network tab)
* Check WebSocket connections
* Inspect Console for error messages
* Test direct localhost access
### Performance problems
**Performance Diagnosis**:
**1. Bundle Size Issues**:
```bash theme={null}
# Analyze bundle size
npm run build # Check build output for large chunks
npx vite-bundle-analyzer dist # Visual bundle analysis
```
**2. Image Optimization Problems**:
```typescript theme={null}
// ❌ Incorrect - unoptimized images
// ✅ Correct - optimized Weaverse images
{expensiveValue}
;
}
// ✅ Correct - memoized expensive operations
function MyComponent() {
const expensiveValue = useMemo(() => expensiveCalculation(), []);
return {expensiveValue}
;
}
```
**Performance Monitoring Tools**:
* React DevTools Profiler
* Chrome Lighthouse
* WebPageTest.org
* Core Web Vitals extension
### Hydration mismatches
**Common Hydration Issues**:
**1. Server/Client Content Differences**:
```typescript theme={null}
// ❌ Incorrect - different content on server/client
function MyComponent() {
return {Date.now()}
; // Different on server vs client
}
// ✅ Correct - consistent content
function MyComponent() {
const [timestamp, setTimestamp] = useState{timestamp || 'Loading...'}
;
}
```
**2. Conditional Rendering Issues**:
```typescript theme={null}
// ❌ Incorrect - browser-only checks during SSR
function MyComponent() {
if (typeof window !== 'undefined') {
return {internalData}
;
}
// ✅ Correct - component updates with prop changes
function MyComponent({ data }) {
const [internalData, setInternalData] = useState(data);
useEffect(() => {
setInternalData(data); // Update when prop changes
}, [data]);
return {internalData}
;
}
```
**3. WebSocket Connection Issues**:
```typescript theme={null}
// Check WebSocket connection in Studio
// Look for connection errors in browser console
// Verify development server is running correctly
```
**Debugging Steps**:
1. Check component props in React DevTools
2. Verify API responses in Network tab
3. Test cache invalidation manually
4. Restart development server
5. Clear browser cache
***
## Support & Resources
### Where do I get help?
**Community Support** (Free):
**1. Slack Community**:
* [Join our Slack](https://wvse.cc/weaverse-slack)
* Real-time chat with developers and the Weaverse team
* Technical support and Q\&A
* Feature requests and feedback
* Component showcase and sharing
* Migration assistance discussions
**2. GitHub Resources**:
* [Documentation Repository](https://github.com/Weaverse/weaverse)
* [GitHub Discussions](https://github.com/orgs/Weaverse/discussions)
* Code examples and issue tracking
**Professional Support** (Paid):
**1. Priority Support**:
* Email support with guaranteed response times
* Technical consultation sessions
* Custom component development
* Migration assistance
**2. Enterprise Support**:
* Dedicated account management
* Custom training sessions
* SLA guarantees
* Priority feature development
### How do I report bugs?
**Bug Reporting Process**:
**1. Check Existing Issues**:
* Search [GitHub Issues](https://github.com/Weaverse/weaverse/issues)
* Check our [Slack community](https://wvse.cc/weaverse-slack) for similar problems
* Review documentation for known limitations
**2. Create Detailed Bug Report**:
````markdown theme={null}
## Bug Description
Clear description of the issue
## Steps to Reproduce
1. Step one
2. Step two
3. Step three
## Expected Behavior
What should happen
## Actual Behavior
What actually happens
## Environment
- Weaverse version: 5.3.4
- Node.js version: 22.0.0
- Browser: Chrome 120
- OS: macOS 14
## Code Sample
```typescript
// Minimal code example that reproduces the issue
````
**3. Include Relevant Information**:
* Screenshots or screen recordings
* Console error messages
* Network requests (if relevant)
* Configuration files
* Steps already attempted
**Bug Report Quality**: High-quality bug reports get faster resolutions!
### Can I request features?
**Yes!** We actively welcome feature requests:
**Feature Request Process**:
**1. Community Discussion**:
* Ask in our [Slack community](https://wvse.cc/weaverse-slack) first
* Gauge interest from other developers
* Refine the feature concept
* Consider implementation approaches
**2. GitHub Feature Request**:
```markdown theme={null}
## Feature Description
Clear description of the proposed feature
## Use Case
Why is this feature needed?
What problem does it solve?
## Proposed Implementation
Ideas for how it could work
## Examples
Similar features in other tools
Mock-ups or wireframes (if applicable)
```
**3. Feature Development Priority**:
* Community upvotes and comments
* Alignment with product roadmap
* Technical feasibility
* Resource availability
**Popular Feature Categories**:
* New input types for schemas
* Enhanced Studio capabilities
* Performance optimizations
* Integration improvements
* Developer experience enhancements
### Is there professional support?
**Professional Support Options**:
**1. Development Services**:
* Custom component development
* Theme customization and optimization
* Migration from other platforms
* Performance auditing and optimization
* SEO optimization
**2. Training Programs**:
* Developer onboarding sessions
* Team training workshops
* Best practices consultation
* Architecture review sessions
**3. Enterprise Solutions**:
* Priority technical support
* Service Level Agreements (SLAs)
* Dedicated account management
* Custom feature development
* White-label solutions
**Support Channels**:
* Email: [support@weaverse.io](mailto:support@weaverse.io)
* Scheduled consultation calls
* Screen sharing technical sessions
* Custom documentation creation
**Pricing**: Contact sales team for professional support pricing based on specific needs.
### Where's the community?
**Primary Community Platform**:
**Slack Community**:
* [Join our Slack](https://wvse.cc/weaverse-slack)
* Real-time discussions with the Weaverse team
* Technical support and troubleshooting
* Feature requests and feedback
* Component sharing and showcase
* Migration help and best practices
* Developer networking and collaboration
**Additional Resources**:
* [GitHub Organization](https://github.com/Weaverse) for code and issues
* [GitHub Discussions](https://github.com/orgs/Weaverse/discussions) for technical discussions
* Official documentation and guides
**Community Guidelines**:
* Be respectful and constructive
* Share knowledge and help others
* Provide detailed information when asking for help
* Contribute to open source projects
* Follow code of conduct
**Getting Involved**:
* Join our [Slack community](https://wvse.cc/weaverse-slack) and help others
* Share components and templates in Slack
* Report bugs via GitHub Issues
* Suggest improvements in GitHub Discussions
* Participate in beta testing discussions on Slack
***
## Still Have Questions?
If you can't find your answer in this comprehensive FAQ:
**Quick Help Options**:
* 🔍 [Search Documentation](/docs) for detailed guides
* 💬 [Join our Slack](https://wvse.cc/weaverse-slack) for community support and real-time help
* 🐛 [GitHub Issues](https://github.com/Weaverse/weaverse/issues) for bug reports
* 💡 [GitHub Discussions](https://github.com/orgs/Weaverse/discussions) for feature requests
**Professional Support**:
* 📧 Email [support@weaverse.io](mailto:support@weaverse.io) for business inquiries
* 📅 Schedule a consultation for complex projects
* 🏢 Enterprise support with dedicated account management
**Learning Resources**:
* 📚 [Complete Tutorial](resources/tutorial) (20-minute walkthrough)
* 🎥 Video tutorials and walkthroughs
* 📖 [Development Guide](/development-guide/index) for advanced topics
* 🧪 [Example Components](resources/example-components) for inspiration
We're always here to help you build amazing Shopify storefronts with Weaverse! 🚀