Deploy Advanced Custom Fields (ACF) with Branch
When building WordPress sites, a lot of our “code” ends up in the database. I put the word code in quotes because it’s a fine line between code and configuration when it comes to WordPress. The more of our code that exists as actual source code in files, the more we can rely on proven software development practices, such as using version control. When our code lives in the database, our lives as developers become more difficult. We lose the ability to use version control, and deploying our code becomes problematic because merging databases is extremely difficult.
Using tools like Advanced Custom Fields (ACF to build a WordPress site, much of what would traditionally have been code ends up in the database as configuration. However, with ACF, it actually doesn’t have to be this way. In this guide, I’ll show you how to make your ACF configuration work more like code.
Introducing Local JSON for ACF
Since version 5, ACF has had a feature called Local JSON, which allows us to store our fields’ configuration in JSON files instead of the database. This has one primary benefit: We can use version control to manage changes to our fields. A great side effect of having version control is that we can use an automated deployment solution such as Branch.
Local JSON works out of the box. All you need to do is add a acf-json folder to your theme, and ACF will start putting your configuration in local JSON files.
Here is how the Git diff looked when I added a new field to my Upload Area field group:
The generated JSON is straightforward and easy to manage with version control, such as Git. This JSON code is now part of our codebase. When we deploy this version of the codebase to another WordPress site (like our production site), ACF will offer to sync that updated configuration into the database:
Syncing JSON changes to the database
One thing that’s less obvious about the Local JSON feature is how data is synced between the database and JSON files. Even though field configuration is still stored in the database, it’s important to know that the JSON configuration always takes precedence over the database. That means that you actually don’t need to sync your changes from the WP dashboard before your field configuration is updated – sort of, at least.
Here’s the ACF sync diff after I changed the email field label from “Your email” to “Uploader’s email” locally, pushed it to Git, and deployed it to my production WordPress site:
Without syncing this, when creating a new post, the field label is showing the new value (from the JSON file):
However, when viewing our fields in WP admin, the old configuration (from the database) is still used until we sync:
So it’s a good idea to remember to sync your configuration to avoid confusion. Note that you probably shouldn’t be editing the values directly on the production site since they will be overwritten when you push new JSON file changes from your local site.
Automated deployments
Once your local field configuration changes are stored in JSON and kept under version control with Git, Branch can automatically deploy them when you push to your Git repository.
Check out our Learn section to learn more about how you can set up automated deployments to your WordPress host of choice.
Using code to manage your ACF configuration
An alternative to using the Local JSON feature is to write your configuration with code. Tools such as ACF Builder are making this possible. ACF Builder offers a fluent API to write your ACF configuration. Here’s an example of how that looks from their docs:
Conclusion
As we’ve seen, there are multiple ways to avoid using the database as the source of truth for your ACF configuration. An important point that I want to make is that other tools* have similar ways to avoid relying on the database. I encourage you to consider this before choosing the next tool in your WordPress toolchain. With less code in your database, your life as a WordPress developer becomes easier.
Sign up to Branch
Signing up for a Branch account is easy. Just head over to branchci.com and sign up with GitHub, Bitbucket or GitLab.
Need Help?
We hope this guide has been helpful, but if you still have any questions or feedback, or if you just want to say ‘hi’, please reach out by clicking the chat icon or by email at hi@branchci.com. Don’t be a stranger!
* Admin Columns is another one.