Tips for upgrading ACF Blocks to block.json

Since the introduction of Advanced Custom Fields (ACF) 6.0, you should be registering blocks using the newer block.json method instead of using the legacy acf_register_block_type() function.

It’s not required to convert your legacy ACF blocks to block.json. Using block.json can come with benefits such as performance improvements and the ability to take advantage of newer WordPress block features.

Use a JSON schema validator

Valid JSON is the best way to ensure your ACF blocks render properly within your theme. The best way to ensure it’s valid is to use the proper schema and validate your JSON file.

Luckily ACF provides a custom schema that extends the native WordPress schema to add ACF specific options.

{
    "$schema": "https://advancedcustomfields.com/schemas/json/main/block.json",
}

For validating JSON schemas I use this Sublime Text 3 extension to make sure everything is happy and valid within the JSON file. This extension checks the JSON in real time and even provides helpful descriptions for each key.

Double-check the ACF key values

Make sure the ACF key values are correct, these key values are specific to ACF blocks. Some of the common key values are:

• mode: The default display mode for the block (auto, preview or edit)
• renderTemplate: The path to the template file used to render the block. This is where all your ACF fields are outputted.
• postTypes: This is used to restrict the block to specific post types.

{
    "$schema": "https://advancedcustomfields.com/schemas/json/main/block.json",
    [...other block.json values go here...]
    "acf": {
        "mode": "preview",
        "renderTemplate": "render.php",
        "postTypes": [ "your-custom-post-type-here", "another-post-type-here" ]
    }
}

No need to specify JSX support

If you previously specified JSX support in your block, there’s no need to enable this feature if you are using API version 2 or higher in block.json.

{
    "apiVersion": 2,
}

Port blocks in small logical batches

If you’re dealing with converting a large number of blocks, it will make your life easier if you convert them in small logical batches. This helps with debugging and testing because you can focus only on the small batch of blocks.

Here are some examples of ways you can group blocks

• Simple blocks that are not project-critical
• Blocks that are restricted to a specific post type (ie: product blocks, promotion blocks)
• Similar functional blocks (ie: CTA blocks, Gallery Blocks, Testimonial Blocks)

Test, test, test!

Most importantly make sure you test your blocks, if everything goes smoothly the user shouldn’t notice any difference.

You’ll want to make sure:

• WP_DEBUG is enabled this will allow you to catch any PHP errors or warnings
• Your browser developer tools are open to catch any JavaScript errors in the console.
• Check for any CSS bugs and media query breakpoints.