Divi 5 Migration: The Complete Guide for Agencies

Divi 5 is a complete rewrite – and your custom modules will initially only run in compatibility mode. What that means and how to migrate properly.

Divi 5 isn’t just an update – it’s a complete redevelopment. Elegant Themes rewrote the builder from the ground up. That brings massive performance benefits, but it also means: your custom modules from the Divi Module Builder need to be adapted.

The problem: compatibility mode

If you built custom modules with the Divi Module Builder or your own extensions, they won’t simply disappear after updating to Divi 5. They keep working – but in what’s called compatibility mode.

In practice, that means you’re building up technical debt. The longer you wait, the more pages use the slow compatibility mode.

What changes technically

Divi 5 is a fundamental change of architecture. Here are the most important differences:

From shortcodes to blocks

The biggest difference: Divi 4 stores modules as WordPress shortcodes:

[et_pb_custom_module title="Hallo Welt" _builder_version="4.27.0"]
  Hier steht der Inhalt...
[/et_pb_custom_module]

Divi 5 uses a JSON-based block format instead:

{
  "id": "module-abc123",
  "name": "d5/custom-module",
  "attrs": {
    "title": {
      "desktop": { "value": "Hallo Welt" }
    }
  }
}

The Divi 5 migrator

Now the good news: you don’t have to touch every page manually! Divi 5 comes with a built-in migrator system:

WordPress Admin → Divi → Divi 5 Migrator

What the migrator does

1. Compatibility check

   Scans your entire website and creates a detailed report: which modules are compatible, which aren’t?

2. Automatic conversion

   All compatible modules are automatically converted from the shortcode format to the new block format.

3. Legacy wrapping

   Modules without Divi 5 support are wrapped in shortcodes and keep running in compatibility mode.

The migration workflow

1. Create an inventory

   List all your custom modules: name, type, number of settings.

2. Clone the extension boilerplate

   Get the official example repo from Elegant Themes.

3. Migrate modules one by one

   Start with the simplest module. Create all the required Divi 5 files.

4. Test on staging

   Activate your new extension on a staging environment. Run the migrator.

5. Go live

   When everything works: create a backup, activate the extension on the live site.

The new file structure

A Divi 5 module consists of significantly more files than in Divi 4:

my-divi5-extension/
├── modules/
│   └── MyModule/
│       ├── MyModuleTrait/
│       │   ├── CustomCssTrait.php
│       │   ├── ModuleStylesTrait.php
│       │   └── RenderCallbackTrait.php
│       └── MyModule.php
├── src/
│   └── components/
│       └── my-module/
│           ├── module.json
│           ├── edit.tsx
│           ├── settings-content.tsx
│           ├── settings-design.tsx
│           └── styles.tsx
├── package.json
└── webpack.config.js

Migration checklist

For each module, you should tick off the following items:

Conclusion and recommendation

Divi 5 is a big step forward – but it takes work. The good news: you don’t have to migrate everything at once.

My recommendation: start migrating your most important modules now. The longer you wait, the more technical debt you pile up.

Michael Rademacher, realmaker

Resources

• Official Example Modules (GitHub)
• Divi 5 Help Center
• Developer Documentation