Support Log in
All Features of Field Forge

Local JSON Sync — Git-Friendly Field Groups

Field Forge writes your field groups as JSON files in your site’s uploads folder (wp-content/uploads/fieldforge-json/). Commit those files to git, and your field group changes become part of your version control history. This is how professional agencies and development teams manage custom fields across multiple environments (development → staging → production) and across multiple team members.


The problem this solves

When you edit a field group in Field Forge’s admin, the change is saved to the WordPress database. Great — until you realize:

  • Your local dev environment has one version of the field group
  • Staging has a slightly different version (because someone edited it there)
  • Production has yet another version (because a content editor added a field directly)
  • You have no history of who changed what, or when, or why

Without version control, field groups drift out of sync. Migrations from dev to production become error-prone. Rollbacks are impossible.

Local JSON sync solves all of this by making field groups file-based alongside being database-based. The database is the source of truth for live editing; the JSON files are the source of truth for version control and deployment.


How it works

Step 1: Enable local JSON sync

In Field Forge → Settings → General, tick the Local JSON checkbox (“Save field groups as JSON files on disk (for version control)”). The save path is shown under it: wp-content/uploads/fieldforge-json/. There is no setting for the folder; a developer can move it with the fieldforge/local_json/save_path filter, inside the uploads folder only.

Step 2: Field groups are saved as JSON

Every time you save a field group in Field Forge’s admin, the plugin also writes a JSON file to the save folder. The filename is group_{id}_{slug}.json — e.g., group_1_hero-section.json.

File contents:

{
  "_fieldforge_version": "1.1.0",
  "_modified": "2026-10-11T09:30:00+00:00",
  "_hash": "5d41402abc4b2a76b9719d911017c592",
  "id": 1,
  "title": "Hero Section",
  "fields": [
    {
      "key": "field_hero_title",
      "label": "Hero Title",
      "name": "hero_title",
      "type": "text",
      "required": true,
      "maxlength": 120
    },
    {
      "key": "field_hero_subtitle",
      "label": "Hero Subtitle",
      "name": "hero_subtitle",
      "type": "textarea",
      "rows": 2
    },
    {
      "key": "field_hero_image",
      "label": "Background Image",
      "name": "background_image",
      "type": "image",
      "return_format": "array"
    }
  ],
  "location_rules": [
    [
      {
        "param": "post_template",
        "operator": "==",
        "value": "template-landing.php"
      }
    ]
  ],
  "menu_order": 0,
  "status": "publish"
}

Step 3: Commit to git

Add the fieldforge-json/ folder to your git repo (or copy it into your theme or plugin repo). Commit field group changes like any other code change.

git add fieldforge-json/group_1_hero-section.json
git commit -m "Add background image field to Hero Section"
git push

Every field group change now has an author, a timestamp, and a commit message. You can diff changes over time, revert to previous versions, and see who added which field.

Step 4: Deploy JSON files to other environments

Deploy the JSON files with your code, or copy them to the other environment’s wp-content/uploads/fieldforge-json/ folder. Field Forge there detects the new or changed files, shows a notice, and imports them when you click Sync JSON → DB.


Bidirectional sync

Local JSON sync works in both directions: saving a field group in the admin writes its JSON file, and Sync JSON → DB applies the files to the database. Sync DB → JSON writes the database field groups to their JSON files.

UI-first workflow

Edit field groups visually in Field Forge’s admin. JSON files are updated on save. Commit JSON files to git. Deploy to other environments.

Code-first workflow

Commit the JSON files that Field Forge writes and deploy them with your code. Field Forge checks when an admin page loads (at most every five minutes) and shows a notice when a file differs from the database; click Sync JSON → DB to update the database. A file counts as changed when its _hash value differs from the hash of the database field group, so a file edited by hand that keeps its old _hash is not detected as a change. A file with a group id that the database does not have is offered as a new field group.

Because change detection compares only _hash, make changes to a field group in the field group editor and let Field Forge write the file. A file that you edit by hand without changing its _hash is not detected as a change, and neither is a file without a _hash.


Change detection

Field Forge compares each JSON file’s content hash to the database version on admin page loads (at most once every five minutes). If they differ, Field Forge:

  1. Shows an admin notice on the Field Forge screens: “Field Forge: N field group(s) have changes in JSON files”, with a Review & Sync link
  2. Shows the same count on the Local JSON Sync card of the Import / Export screen, with two buttons: Sync JSON → DB and Sync DB → JSON
  3. Changes nothing until you click one of them

This prevents silent drift: the files and the database are only brought together when you click. Sync JSON → DB replaces the database version with the file.


Security

Local JSON sync respects WordPress security best practices:

  • .htaccess protection — Field Forge creates a .htaccess file with Deny from all and an index.php in the JSON folder, so servers that read .htaccess files block direct HTTP access
  • Path validation — the plugin writes only inside the uploads folder, in a folder whose name starts with fieldforge; a save path anywhere else is ignored

Load paths

Field Forge reads JSON files from these folders:

  1. The fieldforge-json/ folder of the uploads folder
  2. The save path, when a filter moved it to another folder inside the uploads folder
  3. Any folders added with the fieldforge/local_json/load_paths filter

Theme folders are not read by default. A theme that ships its own fieldforge-json/ folder, or a site whose files an older release wrote into a theme, adds that folder with the filter. The files in it are then applied with Sync JSON → DB.


Multi-site considerations

On a WordPress multisite network, each site has its own uploads folder, so its own fieldforge-json/ folder. To share field groups, add a common folder to the load paths of every site with the fieldforge/local_json/load_paths filter; each site applies the files to its own database with Sync JSON → DB.


Filter hooks for customization

Custom save path

The save path must be inside the uploads folder, in a folder whose name starts with fieldforge. Any other path is ignored.

add_filter('fieldforge/local_json/save_path', function($path) {
    $uploads = wp_upload_dir();
    return $uploads['basedir'] . '/fieldforge-json-shared';
});

Custom load paths (e.g., from a plugin)

add_filter('fieldforge/local_json/load_paths', function($paths) {
    $paths[] = WP_PLUGIN_DIR . '/my-plugin/fields';
    return $paths;
});

Comparison with ACF’s Local JSON

ACF introduced a similar local JSON feature years ago. Field Forge has its own file format, and Local JSON does not read ACF’s acf-json files.

If you’re migrating from ACF with existing acf-json files, the migration tool can read them as a source when the field groups are not in the ACF database tables, and translates them to Field Forge’s format.


Use cases

Agency development workflow

Multiple developers working on client sites. Field groups defined in code, committed to git, deployed via CI/CD. New team members pull the repo and have all field groups after clicking Sync JSON → DB.

Staged deployments

Dev → staging → production pipeline where field group changes travel as files with your deployment. No manual “oh wait, I need to export and import the field groups” step.

Theme distribution

Build a WordPress theme that ships with pre-defined field groups in its own folder. The theme adds that folder with the load paths filter, Field Forge detects the files, and the field groups appear after Sync JSON → DB.

Plugin bundling

A custom plugin that requires specific field groups. Ship the JSON files inside the plugin and register a load path via filter; Field Forge offers the field groups for Sync JSON → DB.


Ready to version control your field groups?

See pricing →

Local JSON sync is included in every version — the free edition on WordPress.org and every paid plan.

Forge AI Assistant Online

Hi! I'm the Field Forge AI assistant. Ask me anything about the plugin — setup, features, troubleshooting, or development.

Just now
Powered by Forge AI · Browse docs