@weaverse/hydrogen v5.8.0 - Enhanced Type Safety & Performance

🚀 @weaverse/hydrogen v5.8.0

Release Date: November 12, 2025

This release brings comprehensive improvements to the WeaverseClient with enhanced type safety, performance optimizations, and better error handling while maintaining backward compatibility.

---

✨ What's New

🏗️ Multi-Project Architecture Support

• Dynamic projectId resolution with priority chain (URL → Function → String → Environment)
• Route-level projectId overrides for campaigns and A/B testing
• Cache isolation per project to prevent cross-project contamination
• Support for synchronous function-based projectId selection

🔒 Enhanced Type Safety

• Leveraged isValidSchema from @weaverse/schema package for comprehensive validation
• Removed unsafe as any type casts throughout the codebase
• Added proper type guards (isFetchProjectPayload, isProjectIdFunction)
• Improved error typing with Record<string, unknown> for flexible context

⚡ Performance Optimizations

• O(1) component lookups: Map-based component registry replacing O(n) array searches
• Cached URL parsing: Eliminates redundant parsing operations in hot paths
• WeakMap memoization: Schema defaults cached with automatic garbage collection
• Optimized data lookup: Reverse iteration with useMemo in React components
• Estimated improvement: 2-5% page load time reduction

🛡️ Improved Error Handling

• Graceful fallback behavior for invalid API responses
• Studio Preview now loads correctly even with malformed data
• Structured WeaverseError class with error codes and context preservation
• Fail-fast validation for immediate feedback on configuration errors
• Proper timeout cleanup with AbortController in finally blocks

🧪 Comprehensive Testing

• Added 19 tests covering all scenarios including edge cases
• Multi-project architecture validation
• Error handling and fallback behavior tests
• Regex constants for maintainable test assertions

---

🔄 Changes

Added

• WeaverseError class for structured error handling with codes and context
• Map-based component registry (componentsByType) for O(1) lookups
• Cached URL parsing (parsedUrl) to reduce redundant operations
• WeakMap cache for schema defaults with automatic garbage collection
• Comprehensive JSDoc documentation with usage examples
• Named constants for magic numbers (CACHE_DURATIONS, DEFAULT_FETCH_TIMEOUT_MS)
• Route-level projectId parameter in loadPage() method
• Project-specific cache keys for better isolation

Changed

• Simplified isValidHydrogenSchema to use isValidSchema from @weaverse/schema
• Improved method organization with extracted helper functions (20-30 lines vs 100+)
• Enhanced error context preservation for production debugging
• Optimized WeaverseHydrogenRoot with useMemo and reverse iteration
• Better input validation with optional allowedKeys parameter in getRequestQueries

Fixed

• Restored fallback page behavior when API responses are invalid
• Studio Preview now loads correctly allowing users to add sections
• Resource cleanup now guaranteed via finally blocks
• Type safety issues in error handling paths

Removed

• Unused zod dependency (validation now handled by @weaverse/schema)
• Unsafe as any type casts replaced with proper type guards

---

⚠️ Breaking Changes

Constructor Validation (Fail-Fast Pattern)

The WeaverseClient constructor now throws immediately when it cannot resolve a valid projectId, instead of logging a warning and continuing with undefined behavior.

Before (v5.7.x):

// Silent failure with console warning
const client = new WeaverseClient({ /* no projectId */ });
// Continued execution with undefined projectId

After (v5.8.0):

// Immediate error throw
try {
  const client = new WeaverseClient({ /* no projectId */ });
} catch (error) {
  console.error('Failed to initialize Weaverse:', error.message);
  // Handle configuration error appropriately
}

Migration: Ensure projectId is provided via:

1. Constructor config parameter (string or sync function)
2. URL query parameter (?weaverseProjectId=xxx)
3. Environment variable (WEAVERSE_PROJECT_ID)

Impact: Low - Most users won't be affected as they provide valid projectId. Users with missing projectId will now get immediate, actionable feedback instead of silent failures.

---

📊 Performance Metrics

Optimization	Before	After	Improvement
Component Lookup	O(n)	O(1)	~10-100x faster for large component lists
URL Parsing	Multiple calls	Cached	Eliminated redundant parsing
Schema Processing	Every render	Memoized	Reduced CPU usage
Page Load Time	Baseline	-2-5%	Measured improvement

---

🔗 Related PRs

• #419 - Comprehensive WeaverseClient refactoring
• Related to multi-project architecture support in v5.7.2

---

📚 Documentation

• Full Documentation: https://docs.weaverse.io
• Migration Guide: See breaking changes section above
• API Reference: https://docs.weaverse.io/api-reference
• Changelog: https://docs.weaverse.io/changelog

---

🙏 Credits

Special thanks to all contributors and reviewers who helped make this release possible!

---

📦 Installation

npm install @weaverse/[email protected]
# or
pnpm add @weaverse/[email protected]
# or
yarn add @weaverse/[email protected]

---

🐛 Known Issues

None at this time. If you encounter any issues, please report them at: https://github.com/Weaverse/weaverse/issues

---

🔜 What's Next

• Enhanced telemetry for configuration error monitoring
• Additional performance optimizations
• Expanded test coverage for edge cases
• Integration examples for common use cases

---

Full Changelog: https://github.com/Weaverse/weaverse/compare/@weaverse/[email protected]...@weaverse/[email protected]

v5.6.0 - Performance Optimization

🚀 Performance Improvements

Data Connector Optimization (91% faster)

• Critical Fix: Resolved 10x page load slowdown on Cloudflare Workers/Oxygen
• Early Exit Optimization: Added hasPlaceholders() function for 90% performance improvement
• Stable Hashing: Replaced JSON.stringify() with WeakMap-based hashing for 9% additional improvement
• Result: 50 components now process in <10ms (previously >1000ms)

📦 Package Updates

All fixed-group packages synchronized to v5.6.0:

• @weaverse/[email protected]
• @weaverse/[email protected]
• @weaverse/[email protected]
• @weaverse/[email protected]

🔧 Technical Details

• Immutability preservation with forceClone propagation
• Comprehensive performance tests to prevent regressions
• Full backward compatibility maintained
• All 91 tests passing

📝 Installation

npm install @weaverse/[email protected]
npm install @weaverse/[email protected]

🔗 Related

• PR: #416
• Commit: ad606bf0

📚 Changelogs

See individual package changelogs for detailed changes:

• packages/core/CHANGELOG.md
• packages/react/CHANGELOG.md
• packages/hydrogen/CHANGELOG.md
• packages/shopify/CHANGELOG.md

🚀 Release v5.4.1: API Cache Proxy Improvements

🚀 Weaverse SDK v5.4.1 - Official Release

This release includes comprehensive API cache proxy improvements and TypeScript build fixes across all Weaverse SDK packages.

🎯 Key Features

API Cache Proxy Improvements

• Migration to withCache.fetch: Updated WeaverseClient to use Hydrogen's withCache.fetch instead of deprecated withCache.run
• Response Structure Unification: Standardized response formats between directFetch and withCache.fetch methods
• Enhanced Cache Strategy: Improved cache key generation and response validation
• Better Error Handling: Added comprehensive error handling for API responses

TypeScript Build Fixes

• Interface Merging: Fixed duplicate type declarations using proper interface merging for module augmentation
• Window Type Declarations: Converted type declarations to interfaces for proper global scope extension
• Environment Variables: Added missing environment variables to HydrogenEnv interface

Code Quality Improvements

• Biome Configuration: Updated to automatically remove unused variables and optimize imports
• Removed Console Logs: Cleaned up debug logging and unused code

📦 Published Packages

All packages are available on npm registry:

• @weaverse/[email protected] - Shared Biome configuration
• @weaverse/[email protected] - CLI tools for Weaverse development
• @weaverse/[email protected] - Framework-agnostic core functionality
• @weaverse/[email protected] - Shopify Hydrogen integration
• @weaverse/[email protected] - React components and utilities
• @weaverse/[email protected] - Shopify-specific utilities

📈 Installation

# Install the main Hydrogen package
npm install @weaverse/[email protected]

# Or install with latest tag
npm install @weaverse/hydrogen@latest

🔄 Migration Notes

This release maintains backward compatibility while improving performance and reliability:

• No breaking changes introduced
• Enhanced cache performance with withCache.fetch
• All TypeScript compilation errors resolved
• Follows Shopify Hydrogen's latest recommendations

🔗 Related Links

• Documentation
• NPM Packages
• Pilot Template

🐛 Bug Fixes & Improvements

• Fixed TypeScript module augmentation issues
• Resolved duplicate type declarations
• Improved API response structure consistency
• Enhanced cache validation logic
• Cleaned up debug code and console statements

---

Full Changelog: View all changes

@weaverse/[email protected]

What's Changed

• Update localization docs by @hta218 in #391
• React Router v7 migration by @paul-phan in #393
• Migrate "inspector" to "settings" by @paul-phan in #394
• Fix CLI instruction path by @paul-phan in #396
• Fix useChildInstances returning undefined by @paul-phan in #395
• Update schema validation by @paul-phan in #399
• Update packages to v5.3.2, fix typo in docs, update biome configs by @hta218 in #398

Full Changelog: https://github.com/Weaverse/weaverse/compare/@weaverse/[email protected]...@weaverse/[email protected]

@weaverse/[email protected]

What's Changed

• Upgrade to React Router v7 & React 19 support.

Full Changelog: https://github.com/Weaverse/weaverse/blob/main/CHANGELOG.md

@weaverse/[email protected]

What's Changed

• Refactor WeaverseClient fetch methods to use arrow functions for better binding by @hta218 in #387

Full Changelog: https://github.com/Weaverse/weaverse/compare/@weaverse/[email protected]...@weaverse/[email protected]

@weaverse/[email protected]

What's Changed

• chore: fix generate default theme settings by @hta218

Full Changelog: https://github.com/Weaverse/weaverse/compare/@weaverse/[email protected]...@weaverse/[email protected]

@weaverse/[email protected]

What's Changed

• chore: update types by @viethung26 in #382
• chore: bump Weaverse packages to version 4.2.2 by @viethung26 in #383
• Update tutorial.md by @altruity in #384
• docs: update environment variables and prerequisites documentation for Weaverse Hydrogen by @paul-phan in #385
• v4.2.4 by @hta218 in #386

New Contributors

• @gmilon made their first contribution in #376
• @altruity made their first contribution in #384

Full Changelog: https://github.com/Weaverse/weaverse/compare/@weaverse/[email protected]...@weaverse/[email protected]

@weaverse/[email protected]

What's Changed

• chore: add navigation doc by @viethung26 in #368
• chore: update docs by @viethung26 in #369
• change linter & formatter to biome by @paul-phan in #370
• Add new video input by @viethung26 in #372
• Weaverse SDKs v3.3.0 by @paul-phan in #373
• Weaverse v3.4.0 by @paul-phan in #374
• Fix weaverseData being cached when url search queries changes by @paul-phan in #375
• chore: request is now mandatory prop createWithCache (2024.10) by @gmilon in #376
• add pilot section docs by @viethung26 in #377
• chore: update docs by @viethung26 in #378
• update docs by @viethung26 in #379
• chore: add preview mode by @viethung26 in #381

New Contributors

• @gmilon made their first contribution in #376

Full Changelog: https://github.com/Weaverse/weaverse/compare/@weaverse/[email protected]...@weaverse/[email protected]

@weaverse/[email protected]

What's Changed

• Weaverse SDKs v3.3.0 by @paul-phan in #373
• Weaverse v3.4.0 by @paul-phan in #374
• Fix weaverseData being cached when url search queries changes by @paul-phan in #375

Full Changelog: https://github.com/Weaverse/weaverse/compare/@weaverse/[email protected]...@weaverse/[email protected]