Fusion Framework #3419 - Major Zod v4 Migration

[odinr]

🎯 Overview

We're excited to announce a new release of Fusion Framework, featuring a major migration from Zod v3 to v4 across the entire monorepo. This release brings improved performance, better TypeScript integration, and enhanced schema validation capabilities.

🔥 Key Highlights

Major Zod v4 Migration

• Complete migration from Zod v3.25.76 to v4.1.8
• Breaking changes requiring major version bumps for core modules
• Enhanced schema validation with improved error handling
• Better TypeScript integration and type inference

Core Package Updates

• @equinor/[email protected] - Major CLI enhancements
• @equinor/[email protected] - React app framework updates
• Multiple module packages updated with dependency improvements

📦 What's Changed

CLI Package (v12.0.0)

• Schema Definitions: Updated to use explicit key and value types for records
• Error Handling: Migrated from .errors to .issues property for ZodError
• Portal Manifests: Updated to use message instead of description for error messages
• Documentation: Enhanced publish command documentation

React App Framework (v7.0.0)

• Updated to support Zod v4 compatibility
• Improved error handling and validation
• Enhanced TypeScript support

Cookbook Applications

• All cookbook applications updated with latest dependencies
• Improved compatibility with new Zod v4 schemas
• Enhanced error handling across examples

⚠️ Breaking Changes

This is a major release with breaking changes due to the Zod v4 migration:

1. Schema Definitions: Record schemas now require explicit key and value types
2. Error Handling: ZodError .errors property changed to .issues
3. Error Messages: Portal manifest schemas use message instead of description
4. Dependencies: All packages now require Zod v4.1.8 or higher

🚀 Migration Guide

For CLI Users

# Update to latest version
pnpm add -g @equinor/[email protected]

# Verify installation
ffc --version

For Application Developers

# Update your project dependencies
pnpm update @equinor/[email protected]
pnpm update @equinor/[email protected]

Schema Migration

If you have custom schemas, update them to use explicit types:

// Before (Zod v3)
const schema = z.record(z.any())

// After (Zod v4)
const schema = z.record(z.string(), z.any())

👾 Fusion Issues

• https://github.com/equinor/fusion/issues/656

🐛 Bug Fixes & Improvements

• Enhanced Error Messages: More descriptive validation errors
• Improved Performance: Better schema validation performance
• Type Safety: Enhanced TypeScript integration
• Documentation: Updated CLI documentation for publish commands

📚 Documentation Updates

• Updated CLI documentation with improved publish command guidance
• Enhanced error message formatting
• Improved schema validation examples

🔗 Related Links

• Full Changelog
• Zod v4 Migration Guide
• Fusion Framework Documentation

🙏 Acknowledgments

Special thanks to the development team for the comprehensive migration effort and the community for their feedback during the development process.

---

Ready to upgrade? Simply update your dependencies for Fusion Framework and let us know if you encounter any issues!

#FusionFramework #Release #ZodV4 #TypeScript #React

[v3gard]

@odinr Is there any breaking changes from v11 to v12 for app teams like mine that we need to consider?

Btw, the migration guide link points to https://equinor.github.io/fusion-framework...

[odinr]

nope, "for mye armer og bein" today, Zod is only used internally, no migration needed

✅ i`ll update the miss-leading text

Zod v3 -> v4 had some major overhaul and required some internal changes, so we went for a major patch version of affected packages.