Deprecating a block – dealing with a larger codebase

If you’ve created a block plugin that’s in use anywhere other than on sites that you manage, then making sure you manage block deprecation when editing the save function or block attributes for a static block is something you may be familiar with.

The developer.wordpress.org resources for understanding block deprecations are very useful – the tutorial highlights practically what the reference guide points out, for a couple of examples.

If your block contains large files / lots of code, or if you working on a codebase with block code that you aren’t familiar with, then here are some key points I found useful when I was recently in a similar situation.

File structure

With a larger block code-base, a single deprecated.js file may be too large or difficult to read or maintain. You may also want to include different block deprecation versions.

Ordinarily you’d import your deprecated.js file into the file where you register your block with registerBlockType, but for more flexibility you can instead create a deprecated directory with an index.js file, and within that you can export relevant deprecation versions, which can be found within sub-directories v1, v2, etc. Each of those can hold it’s own index.js file – which is the equivalent of the deprecated.js file in simpler examples.

An example index.js in the deprecated directory could look like:

import * as deprecatedV1 from './v1';
import * as deprecatedV2 from './v2';

export default [ deprecatedV2, deprecatedV1 ];

Simplify the main deprecation file

If the file itself with your previous save functionality as well as attributes in it is quite large, remove the attributes and place them in their own file, making sure to import it. Got any supports? Put those in a separate file too. Whatever makes your file easier to read.

Add all dependencies

Adding all attributes and a modified save function into your deprecated.js (or relevant index.js in examples with a deprecated directory and versioned sub-directories) can be fine unless your save function itself has dependencies. Consider a save function that returns a custom component for example. You’ll need to then copy the code for that custom component into the deprecated.js or index.js file as well (unless that component is never likely to have modifications made to it). This is to prevent your block deprecation from breaking unexpectedly because your custom component has since changed and won’t work with the previous code in your save function.

Those custom components may not be small. Adding them to their own files within the versioned sub-directory (eg. v1 in the deprecated directory) would be better here. This also includes imports that your custom component uses ( which can also include stylesheets ) – so you may end up with a few additional files just to make sure the functionality for your save function will work as expected.

What will it look like?

In the end, you may end up with something that has a structure similar to the following (simplified) structure:

- my-block/
  - deprecated/
    - index.js
    - v1/
      - index.js
      - custom-component.js
      - attributes.js
      - style.css
    - v2/
      - index.js
      - custom-component.js
      - attributes.js
      - style.css

Testing your changes

When it comes to testing out whether your new block deprecation works, remember that it is expected that you need to update the post first (for example adding a new block or making some other change to the page), and only then will the new version of the content appear on the front-end.