How to avoid conflicts when using the ACF Local JSON feature

Best practices for development teams who use ACF Local JSON in version control

Local JSON is a handy feature of the Advanced Custom Fields plugin that allows developers to add all a site’s field group settings to a Git repository for version control.

When a new field group is saved a JSON file is created for the field group. This JSON file is saved in the theme folder in a acf-json sub folder. This makes it easy to include the JSON in a site’s Git repository.

There are however some issues that can arise when using this feature.

Issues? Like what?

Here’s an example involving a local development copy of a site, the production (or live) version of a site and a team of two developers.

Developer A adds a new field to existing Field Group X on their local copy of the site. They save the field group and the related JSON file (and it’s `modified` value) is updated in the site’s theme. Developer A then starts work on adding support for the new field to the theme’s templates.

While Developer A is making the required changes to the theme, Developer B logs into the WordPress admin on the production copy of the site. The content editor of the site is confused about the purpose of an existing field in Field Group X. So Developer B adds some instructions to the offending field’s settings to improve the site’s usability for the content editor. Developer B saves the field group which updates the field group’s `modified` value in the site’s database. Easy fix. Problem solved.

Developer A finishes testing the new feature on their local copy of the site. They commit the updated JSON for Field Group X and deploy it to the production site along with the related theme template changes.

Developer A logs into the WordPress admin for the production site and discovers that not only is their updated JSON not being used by ACF but also there is no “Sync” option available for Field Group X. ACF is ignoring the JSON file that contains the new field.

What’s going on?

“JSON field groups will be available for sync when either the JSON field group does not exist in the DB, or when the JSON field group contains a higher ‘modified’ value (within the JSON array) than the DB post’s modified date.” – advancedcustomfields.com

The `modified` value of Field Group X in the production database is more recent than the `modified` value in the JSON file deployed via version control. So ACF uses the field group settings in the database and ignores the JSON file.

(The other issue here is that the field instructions added by Developer B are not in the theme repository.)

Have a read of this follow up article to understand more about where ACF field settings are stored and read from.

The preventative workflow

You can prevent conflicts like this with a simple workflow first suggested to me by Aaron Rutley (coauthor of the ACF Theme Code plugin).

1. Keep ACF field groups out of the production site’s database.
   Ideally all field groups should be loading from the JSON in the theme’s repository. The ACF Field Groups admin page should not show any field groups available for editing. Just a “Sync available” option for all the site’s field groups. This sync option should never be used on the production site, even for debugging or quick fixes as it will add the field group to the database.
2. Only make changes to field group settings locally.
   To do this a developer should first pull the latest JSON from the repository. Then sync the required field group via the ACF Field Groups admin page on their local copy of the site. This will add the field group to their local DB. Once the required changes have been made to the field group, saving it will update the local JSON (and the database). These JSON changes can then be committed to the repository and deployed to the production site. Because the production site is only loading field groups from JSON (and never the database) the field group settings in the repository will always be used.
3. Hide the ACF Field Groups admin page on the production copy of the site.
   This is protection against a new or forgetful developer syncing and editing field groups. See the Hide the ACF admin menu item on selected sites snippet for more information.

Please note this workflow assumes that the production database is only ever “pulled” with tools like WP Migrate DB Pro.