Storing ACF JSON files locally allows you to maintain version control over your custom fields, making it easier to track changes and collaborate.

Creating an acf-json Directory

Create a Directory:

• Create a folder named acf-json inside your plugin or theme directory.

---

Saving ACF JSON in a Plugin

To enable local JSON storage for ACF, follow these steps:

To save ACF JSON files within a plugin, add the following code to your plugin file:

// Define plugin directory path.
define( 'PLUGIN_DIR_PATH', untrailingslashit( plugin_dir_path( __FILE__ ) ) );

// Filter to update JSON save path.
add_filter( 'acf/settings/save_json', 'my_acf_json_save_point' );

function my_acf_json_save_point( $path ) {
    // Set new save path.
    $path = PLUGIN_DIR_PATH . '/acf-json';
    return $path;
}

Saving ACF JSON in a Theme

If you create an acf-json directory inside your theme’s root, ACF automatically saves JSON files there. However, if you want to change the directory name (e.g., from acf-json to acf-groups), use the following code in your functions.php file:

// Define theme directory path.
define( 'THEME_DIR_PATH', untrailingslashit( get_template_directory() ) );

// Filter to update JSON save path.
add_filter( 'acf/settings/save_json', 'prefix_acf_json_save_point' );

function prefix_acf_json_save_point( $path ) {
    // Set new save path.
    $path = THEME_DIR_PATH . '/acf-groups';
    return $path;
}

Now, when you save or update an ACF field group, the JSON file will be generated in the specified folder.

If you have multiple ACF groups, separate JSON files will be created for each.

---

How ACF Loads JSON Files?

During initialization, ACF automatically loads .json files stored inside the acf-json directory within your theme.

If you want to change this loading path to a plugin directory, use the following code:

<?php
// Define plugin directory path.
define( 'PLUGIN_DIR_PATH', untrailingslashit( plugin_dir_path( __FILE__ ) ) );

// Filter to modify JSON load path.
add_filter( 'acf/settings/load_json', 'prefix_acf_json_load_point' );

function prefix_acf_json_load_point( $paths ) {
    // Remove default path.
    unset( $paths[0] );
    
    // Set new load path.
    $paths[] = PLUGIN_DIR_PATH . '/acf-json';
    
    return $paths;
}
?>

This ensures that ACF loads field group JSON files from your plugin directory instead of the default theme location.

Syncing ACF JSON Files

ACF allows syncing of JSON field groups when:

• The JSON field does not exist in the database.
• The JSON file has a newer modified timestamp than the database version.

To sync, navigate to Custom Fields → Field Groups, and click on the Sync Available button. You will see all available JSON files ready for import. Click Import to sync the changes.