If you’ve ever worked with Advanced Custom Fields (ACF), you’ll know how easy it is to end up with a maze of unsynced field groups, especially when working across multiple environments or as part of a team.
I use ACF JSON on almost every project to avoid that pain. It’s a simple but powerful feature that lets you version-control your fields, keep local edits in sync, and avoid accidental overwrites when moving between local, staging and live sites.
In this post, I’ll walk through what ACF JSON is, how to enable it, and why it’s one of the best small changes you can make to improve your WordPress workflow.
What is acf-json?
Normally, ACF saves your custom fields in the database. That works fine… until you need to:
- Move fields between staging and production
- Work in a team without overwriting each other’s changes
- Roll back field changes with version control
- Speed up WordPress by reducing database queries
This is where acf-json comes in. When enabled, ACF saves field groups as JSON files in your theme, making them portable, trackable, and much faster to load.
How to Enable acf-json (only takes 30 seconds!)
ACF actually supports this out of the box—you just need to set it up.
1. Create a folder in your theme:
/wp-content/themes/your-theme/acf-json/2. Save a field group in ACF → it will automatically generate a JSON file inside that folder.
That’s it – no plugins, no extra setup.
To make sure it’s working
Check your acf-json folder in your theme and you’ll see a file will have appeared, named something like group_4435395845.json. This contains all the info about your ACF field and will update automatically whenever you save changes in ACF. See below:
ℹ️ You can also edit these .json files directly, if you know what you’re doing. You’ll just need to sync it in ACF afterwards!
Syncing field groups across environments
If you do edit your .json file directly or, for example, another developer makes some ACF changes on a staging site, then you’ll need to sync your changes. This is super simple, and all you need to do is:
- Login to WordPress.
- Go to ACF > Field Groups.
- Check across the top where you should see ‘Sync Available’ as an option (See screenshot below).
- Click this, and then sync all fields that you want.
What if you already have ACF fields, but want to introduce acf-json?
If you already have a bunch of ACF fields set up, but want to start using acf-json, no worries!
- Still follow the same steps above, however you will notice your .json files don’t magically appear in the
acf-jsonfolder. - Go to WordPress Admin > ACF > Field groups
- Check all your field groups and ‘deactivate’ them.
- Re-activate them all
- This saves your ACF fields, and therefore creates the .json files in the
acf-jsonfolder.
Why you should be using this
- No more “Why aren’t my fields updating?”
- No more copy-pasting fields between sites
- No more “Oops, I overwrote your ACF changes”
- Faster WP Admin with fewer database queries
To wrap up
ACF JSON might feel like one of those “nice to have” features, that is, until you try it! Once it’s in place, syncing field groups becomes seamless, and it makes a huge difference.
It’s one of those small things that makes a huge difference, that I always include when setting up a custom WordPress build.
If you’re looking to improve your editing experience or streamline your dev workflow, I’d love to help.
Drop me a message and let’s talk about what’s possible.
