Local JSON

Overview

Local JSON is a new feature added in version 5 which saves field group and field settings as .json files within your theme. The idea is similar to caching, and both dramatically speeds up ACF and allows for version control over your field settings!

Getting started

To start using the local JSON feature, simply create a new folder in your theme and name it acf-json. This folder must have permissions for the server to read and write (in most cases 755 will work well).

Once this folder exists, each time you save a field group a JSON file will be created (or updated) with the field group and field settings. The JSON file will be named using the field group’s unique key.

Now that the JSON file exists, ACF will load the relevant field group and field settings from this file which reduces the number of database calls during your page load!

Saving explained

Each time you save a field group a JSON file will be created (or updated) with the field group and field settings. The JSON file will be named using the field group’s unique key. Only 1 save point (folder) exists and can be customized by adding the following code to your theme.

<?php
 
add_filter('acf/settings/save_json', 'my_acf_json_save_point');
 
function my_acf_json_save_point( $path ) {
    
    // update path
    $path = get_stylesheet_directory() . '/my-custom-folder';
    
    
    // return
    return $path;
    
}
 
?>

Loading Explained

During ACF’s initialization procedure, all .json files within the acf-json folder will be loaded. By default ACF looks for a folder within your theme called acf-json, however, this is only 1 of the load points which can be added

To add a new load point (folder) for ACF to look in, please add the following code to your theme or plugin.

<?php 

add_filter('acf/settings/load_json', 'my_acf_json_load_point');

function my_acf_json_load_point( $paths ) {
    
    // remove original path (optional)
    unset($paths[0]);
    
    
    // append path
    $paths[] = get_stylesheet_directory() . '/my-custom-folder';
    
    
    // return
    return $paths;
    
}

?>

This filter will allow plugin and theme developers to easily register field groups which cannot be edited by clients.

Syncing changes

The real power in ‘local JSON’ is the ability to sync changes. This allows multiple devs to work on a project, use git to push / pull files, and keep all databases synchronized with the latest field group settings!

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.

When fields groups are detected for synchronization, you will see a new tab above the field group list where you can select the groups to be imported.

acf-pro-sync-available

Security

If you wish to hide your field group or field settings from the public, simply add an empty index.php file to your acf-json folder. WP use the same method to hide the wp-content/themes folder, they like to add a message too 👍.

index.php

<?php
// Silence is golden.
?>

Save

Save

Related

⏰ It's finally time! ACF PRO pricing changes take effect on Monday, 24th February. Learn more

We use cookies to offer you a better browsing experience, analyze site traffic and personalize content. Read about how we use cookies and how you can control them in our Cookie Policy. If you continue to use this site, you consent to our use of cookies.