Migrating From Version 2 to Version 3

Stackable version 3 comes with big changes in your workflow and a lot of new features. This article will help guide you easily migrate to version 3 coming from version 2.

Important: Version 3 is fully backward compatible with version 2, and you won't need to rebuild any of your web pages.

What's new in Version 3?

To learn what's new in version 3, you can check this doc What's New in Version 3?

Version 3 of Stackable comes will brand new blocks which are meant to replace all the old Stackable blocks. These new blocks are faster, more flexible, and more powerful.

While the new v3 blocks will replace the old v2 blocks, you can still use the old blocks as you normally would.

Here's what the old blocks now look like vs the new ones:

Updating to Version 3

After upgrading your plugin, you will automatically be redirected to the Stackable V3 Onboarding Wizard.

You will be asked how you would like to transition your workflow when editing to your pages. You will need to choose 1 out of the 3 options that are provided:

1. Use Old V2 Blocks, but Only When Editing Existing Posts

  • If you choose this option, Stackable will only add the version 2 blocks if you are currently editing any Posts or Pages that consist of version 2 blocks.
  • Whenever you edit your existing posts that have v2 blocks, you will be able to insert and edit v2 blocks. You will also be able to use v3 blocks alongside them.
  • When you create new posts/pages, you will then only be able to insert the new v3 blocks.
  • When to use this option? Select this if you have existing posts and pages which already use v2 blocks which you want to leave as-is, and for your future posts, use the new v3 blocks. Select this also if you're using reusable blocks with v2 blocks that you plan on still using.

2. Use Both New V3 and Old V2 Blocks

  • If you choose this option, both version 2 and version 3 Stackable blocks will be added to your editor. It will not matter if you don't have any Posts or Pages that use any version 2 blocks.
  • When to use this option? Use this option if you want to always use both v2 and v3 blocks across your entire site, even for new posts/pages.

3. Use New V3 Blocks Only

  • If you choose this option, the version 2 blocks will not be added to your editor and all of your Stackable blocks will be for version 3.
  • Note that if you have Posts or Pages that make use of version 2 blocks, choosing this option will not affect how it looks on your site. However, you will just not be able to edit them since the version 2 blocks won't be added to your editor (they will show a block error, but this should have no impact in the frontend)
  • When to use this option? Use this option if you want to only use the new v3 blocks moving forward, don't intend to edit your old pages or intend to rebuild them (remember, you don't need to rebuild anything when upgrading from v2 to v3!)
Important: Opting to have your existing pages still use v2 blocks won't slow down your website. It would still continue to perform as it would previously.
Important: We recommend enabling the Optimization Setting so that the v2 styles and scripts would only get loaded when v2 blocks are used in the page

Design Library

The Design Library has been upgraded as well. You can toggle between the old Design Library and the new one. But keep in mind that the old Design Library uses the old v2 blocks, and the new Design Library uses the new v3 blocks.

You will also have the option to choose whether to load the old Design Library that use v2 blocks or use the new Design Library in order to have access to the version 2 UI Kits and Block Designs, or to load the version 3 Design Library.

Changing Settings After the Wizard is Completed

The wizard will not show up again after completion, but you can always change whether or not v2 blocks are loaded by heading over to Settings > Stackable in your admin and scrolling to the bottom: