Full Stack Web Developer


Synchronizing ACF fields across environments

Starting from version 5, ACF introduced the so-called 'Local JSON' technique to easily sync custom fields across all software development environments.

Ads: Register now via this link to receive $100 credit from Vultr

If you’re a WordPress developer, the term ACF or Advanced Custom Fields will be pretty much familiar. The ACF plugin has been playing a crucial part in Plugin and Theme development for a very long time by providing numerous fields that help create complex layouts and flexibility in terms of logic.

As a developer, you will work at least in three software development environments, namely the local environment, staging environment and the production environment.

As ACF fields are stored in the database, whenever you make any change to the existing fields or create a new one in your local development, you will need to export or manually do it again on the staging and production environments. This is not a best practice though, as it consumes a lot of time and can be error-prone.

Starting from version 5, the ACF plugin provides a smart way to solve this problem. It introduced a so-called Local JSON in which ACF will store the version of each custom field in a folder named acf-json, or any preferred folder name.

Putting your custom fields under version control

This is not about git or any other version control software, but it’s all about the technique that ACF provides. To do so, you will need to manually create a folder under your theme or plugin directory called acf-json with the permission of 755 so that ACF could read and write into that folder.

In case you wish to create your own name, ACF also provides an option to do so by altering the path in the acf/settings/save_json filter like below:

add_filter( 'acf/settings/save_json', 'my_acf_json_save_point' );
function my_acf_json_save_point( $path ) {
    // update path
    $path = get_stylesheet_directory() . '/my-custom-folder';
    // return
    return $path;

After that, whenever you create a new custom field or update the existing ones, a JSON file will be created (or updated) with the field group and field settings as its content.

JSON files created under the acf-json folders
ACF stores a JSON file for each custom field (created or updated) with the field group and field settings.

How can other environments see the change?

First of all, your theme or plugin files must be under version control, whether git or SVN or any other version control software out there.

On each environment server, during its initialize process, ACF will look in the acf-json folder (or your preferred name folder) and load them.

Again, if you’d like to use your own preferred name folder, add the following code to your functions.php file:


add_filter( 'acf/settings/load_json', 'my_acf_json_load_point' );

function my_acf_json_load_point( $paths ) {
    // remove original path (optional)
    // append path
    $paths[] = get_stylesheet_directory() . '/my-custom-folder';
    // return
    return $paths;

Synchronizing the change

This is the cool part of the process. Our initial purpose was to load the changes of the custom fields on other environment servers once one of them has files changed.

On each server, ACF will check for the custom fields in the acf-json folder (or your own folder name) to load by comparing the JSON array with the DB post’s modified date.

If this condition falls true in one of the environments, at the Custom Fields, you will see the Sync available tab above the field groups.

Just choose Sync from the dropdown and hit apply, then the changes will be applied right on your current server. (Image: ACF)

Simply choose the fields you wish to get synced, and then from the dropdown box beneath it, select Sync and click on Apply button.

That’s it! Should you have any questions, or wish to share your own experience, please do so in the comment below.

Leave a Reply

Your email address will not be published. Required fields are marked *