Purpose

This article provides a comprehensive guide for upgrading the Puck Editor plugin from version 0.17.4 to 0.21.1. It covers scope, implementation steps, and required code changes while ensuring backward compatibility with existing page structures.

• Understand breaking changes and migration steps
• Upgrade package and architecture
• Improve Page Builder usability and performance

Overview

The Puck upgrade introduces UI improvements, enhanced editing capabilities, and architectural updates such as migration from Dropzone to Slot-based rendering.

• Improved Page Builder UI and navigation 
• Enhanced editing experience
• Scalable and future-ready architecture

Key Enhancements

• Plugin Rail for better navigation
• Keyboard shortcuts (Delete & Backspace)
• Resizable sidebars
• Drag-and-drop support for existing widgets
• Improved Outline navigation
• Migration from Dropzone to Slot architecture
• Automatic legacy page JSON migration

Problem Statement

The previous version (v0.17.4) had the following limitations:

• Existing widgets could not be moved into Flex containers
• Outline panel did not focus on selected widgets
• Increased manual effort for page editing

Solution

1. Slot-Based Architecture

• Replaced all Dropzone implementations
• Introduced Slot-based rendering
• Improved flexibility and scalability

2. Legacy Page JSON Migration

• Automatic migration utility implemented
• No manual intervention required
• Ensures backward compatibility

3. Migration Guard Logic

• Runs only for legacy page structures
• Prevents redundant processing
• Ensures data integrity

Upgrade Workflow

Step 1: Package Upgrade

• Remove@measured/puck
• Add@puckeditor/core@0.21.1

Step 2: Update Imports

• Replace all imports from@measured/puck to@puckeditor/core

Step 3: Hook Migration

• ReplaceusePuck() withuseGetPuck()

Step 4: Dropzone to Slot Migration

• Replace all <Dropzone /> components
• Add slot definitions in component config

fields: {
  Container: {
    type: "slot"
  }
}

• Replace:

<Dropzone zone="Container" />

• With:

<Container />

Step 5:  Legacy page JSON Migration Utility

To support backward compatibility for pages created using Puck v0.17.4, a migration utility has been introduced to automatically transform existing page data into the new structure supported by the upgraded Puck editor.

This ensures that previously created pages continue to function without requiring any manual updates.

Location

packages/page-builder/src/utils/common.ts

Migration Strategy

• Introduced a function named migrateLegacyPageStructure.
• This function handles migration of legacy page data into the new page structure.
• The migration process includes:
  • Main page content
  • Header data
  • Footer data
• The migration logic internally uses a helper method migrateLegacyData.

Migration Guard Logic

• The migration process runs only when legacy zones are detected in the page JSON.
• If the page data is already in the new format, the migration process is skipped.
• This approach prevents redundant processing and ensures data integrity.

Key Benefits of the Solution

• Provides seamless backward compatibility for existing pages.
• No manual intervention is required to migrate legacy page data.
• Improves performance by avoiding repeated migrations. 
• Reduces the risk of data corruption.
• Ensures the page architecture is aligned with the latest Puck editor standards.

Important Note

No manual changes are required for this migration. The utility automatically converts the old page JSON structure into the new page JSON format.

This migration function is invoked in:

• PageEditor.tsx – Used in the Page Builder (Admin).
• PageRender.tsx – Used on the Webstore during page rendering.

This ensures that both the admin page builder and the storefront correctly handle legacy page structures.

Page Rendering and Legacy Migration Flow

During page rendering, the system checks whether the page JSON follows the legacy structure. If legacy zones are detected, the migration utility converts the data into the new format before rendering the page.

This ensures that pages created with earlier versions of the Puck editor continue to render correctly without requiring any manual updates.

• Register components and slots
• Ensure proper rendering of nested structures

Impact on Custom Components

Custom components using Dropzone must be updated.

• Replace Dropzone with Slot
• Add slot definition in config
• Update LAYOUTS mapping

Failure to update may result in:

• Broken layouts
• Rendering issues
• Data incompatibility

Common Issues & Fixes

1. Module Not Found

• Replace@measured/puck with@puckeditor/core

2. Deprecated Hook

• ReplaceusePuck() withuseGetPuck()

3. Dropzone Breaking Change

• Convert Dropzone to Slot
• Update component config and mapping

4.  Extra node (div) added in DOM when replacing Dropzone with slot

• Remove unnecessary wrapper classes
• Move styling to layout config

Benefits

• Improved user experience
• Better performance
• Future-ready architecture
• Seamless backward compatibility

Reference

For more details, refer to the official documentation:
 Puck Editor v0.21.1 Updates