ACF Synchronized JSON: How to Sync Fields Without Exporting

If you’re working on WordPress projects with multiple environments – local, staging, and production – you know how frustrating it can be to keep Advanced Custom Fields (ACF) field groups in sync across them.

In this guide, you’ll learn how ACF’s Local JSON feature works, how to enable it, how to sync field groups between environments, and how to customize save/load paths for advanced workflows.

Local JSON has been available in the free version of ACF since version 6.0. You no longer need ACF PRO to use this feature. It works with field groups, post types, taxonomies, and options pages.

The Problem: Keeping Fields in Sync

Without Local JSON, transferring ACF field groups between environments requires either exporting and importing JSON/PHP files manually, or syncing the entire database. Both approaches are tedious and error-prone.

Even small changes – like adding a single field to a group – meant repeating that change manually on every environment, or doing a full database migration that could overwrite other data.

I’ve written extensively about ACF and rely on it for nearly every custom project. Local JSON solves this sync problem elegantly by turning your field definitions into version-controlled files.

What Is ACF Local JSON?

Local JSON automatically saves your ACF field groups as JSON files inside your theme directory. Whenever you create or edit a field group in the WordPress admin, ACF writes a corresponding JSON file. This means:

• Your field definitions live in the filesystem, not just the database
• You can track changes with Git alongside your theme code
• You can deploy field changes by simply pushing files – no export/import needed
• ACF loads fields from JSON files first, which is faster than database queries

Each field group is stored as a separate JSON file, named after the group’s unique key (e.g., group_abc123.json). The file contains all field settings, including sub-fields, conditional logic, and display rules.

How to Enable Local JSON

Create a folder named acf-json inside your active theme (or child theme) directory:

mkdir wp-content/themes/your-theme/acf-json

For security, add an index.php file to prevent directory listing:

<?php // Silence is golden. ?>

That’s it. From now on, any field group you create or edit will be automatically saved as a JSON file in this folder.

Syncing Fields on Another Installation

To reuse the same fields on another WordPress site:

1. Copy the acf-json folder into the same theme directory on the new site (or push via Git)
2. In the WordPress admin, go to Custom Fields > Field Groups
3. If ACF detects JSON files that aren’t yet in the database, you’ll see a “Sync Available” tab
4. Select the groups you want to sync and click “Sync”

ACF marks a field group as “available for sync” when either:

• The group exists in JSON but not in the database
• The JSON file has a newer modified timestamp than the database version

Customizing Save and Load Paths

By default, ACF uses the acf-json folder in your active theme. You can override both the save path and load paths with filters:

add_filter( 'acf/settings/save_json', function( $path ) {
    return get_stylesheet_directory() . '/acf-json';
} );

add_filter( 'acf/settings/load_json', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/acf-json';
    return $paths;
} );

This is useful when you want to:

• Store JSON files in a plugin instead of a theme
• Load field groups from multiple locations (e.g., a shared library)
• Keep ACF JSON files outside the theme for better separation of concerns

Since ACF 6.2, you can also use more granular filters to customize paths based on the field group key or type. See the official Local JSON documentation for details.

Local JSON vs PHP Registration

ACF offers two ways to define fields in code: Local JSON and PHP registration via acf_add_local_field_group(). Here’s how they compare:

Most developers use Local JSON during development (for flexibility) and switch to PHP registration for production if they want to prevent accidental field edits.

Best Practices

• Commit JSON files to Git: Treat them as part of your codebase, not disposable files
• Don’t edit JSON files manually: Always make changes through the WordPress admin and let ACF regenerate the JSON
• Use a child theme: Store the acf-json folder in your child theme to survive parent theme updates
• Add acf-json to your deployment: Make sure your deployment pipeline includes the folder
• Review diffs before merging: JSON diffs can reveal unintended field changes made by other team members

FAQs

Common questions about ACF Local JSON:

Summary

ACF Local JSON turns your field groups into version-controlled files by automatically saving them as JSON in your theme’s acf-json folder. This eliminates the need for manual export/import and makes field deployment as simple as pushing code.

The feature is available in the free version of ACF since 6.0. To get started, create an acf-json folder in your child theme, and ACF handles the rest. On other environments, use the “Sync Available” tab to pull in field changes from the JSON files.

For production sites where you want to lock down fields completely, consider registering fields via PHP instead. For everything else, Local JSON strikes the right balance between flexibility and version control.