Local JSON Sync for WordPress Custom Fields

Field Forge auto-saves your field groups as JSON files in your WordPress theme’s directory. 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 → Local JSON, enable the feature. Specify a directory in your active theme where JSON files should be saved (default: wp-content/themes/your-theme/fieldforge-json/).

Step 2: Field groups auto-save as JSON

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

File contents:

{
  "key": "hero-section",
  "title": "Hero Section",
  "fields": [
    {
      "key": "field_hero_title",
      "label": "Hero Title",
      "name": "hero_title",
      "type": "text",
      "required": true,
      "max_length": 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": [
    [
      {
        "param": "post_template",
        "operator": "==",
        "value": "template-landing.php"
      }
    ]
  ],
  "position": "normal",
  "style": "default"
}

Step 3: Commit to git

Add the fieldforge-json/ directory to your theme’s git 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

When you deploy your theme to staging or production, the JSON files come with it. Field Forge on the destination environment detects the new or changed JSON files and imports them automatically.

Bidirectional sync

Local JSON sync is bidirectional — you can edit field groups via the admin UI (which updates both the database and the JSON file) OR by editing JSON files directly (which updates the database the next time Field Forge loads).

UI-first workflow

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

Code-first workflow

Edit JSON files directly in your IDE (VS Code, PhpStorm, etc.). On the next page load, Field Forge detects the JSON changes and updates the database. Commit JSON files to git.

Both workflows are supported. Teams typically use the UI for new field groups and code editing for small adjustments.

Change detection

Field Forge compares each JSON file’s content hash to the database version on load. If they differ, Field Forge:

Shows an admin notice: “Field group ‘Hero Section’ is out of sync with local JSON”
Offers options: “Sync from database to JSON” or “Sync from JSON to database”
You click the direction you want and Field Forge updates accordingly

This prevents silent drift. If someone edits a field group on production directly (bypassing the dev → staging → prod workflow), you see a notice the next time you deploy.

Security

Local JSON sync respects WordPress security best practices:

.htaccess protection — the JSON directory is protected from direct HTTP access by default (a .htaccess file blocks it)
File permissions — JSON files are created with standard WordPress file permissions (644)
Path validation — the plugin only reads JSON files from the configured directory (no path traversal)

Parent + child theme support

Field Forge checks multiple load paths for JSON files:

Active theme’s fieldforge-json/ directory
Parent theme’s fieldforge-json/ directory (if child theme is active)
Any custom paths registered via fieldforge/local_json/load_paths filter

This means a parent theme can ship field groups via JSON, and child themes can override or extend them.

Multi-site considerations

On a WordPress multisite network, each site has its own fieldforge-json/ directory. Network administrators can choose between:

Per-site JSON files — each site has its own field groups
Shared JSON files — field groups defined in the parent theme apply to all sites that use it
Hybrid — some field groups shared, some per-site

Filter hooks for customization

Custom save path

add_filter('fieldforge/local_json/save_path', function($path) {
    return WP_CONTENT_DIR . '/custom-fieldforge-json';
});

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’s implementation is largely compatible — field group JSON files from ACF can be imported into Field Forge’s JSON directory with minor format adjustments (Field Forge adds a few metadata fields ACF doesn’t track).

If you’re migrating from ACF with existing JSON files, Field Forge’s migration tool reads them during import and translates them to Field Forge’s format automatically.

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 immediately.

Staged deployments

Dev → staging → production pipeline where field group changes travel with theme updates. 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. Users install the theme, Field Forge detects the JSON files, field groups appear automatically.

Plugin bundling

A custom plugin that requires specific field groups. Ship the JSON files inside the plugin, register a load path via filter, field groups activate when the plugin activates.

Ready to version control your field groups?

Get Field Forge — from $35/year →

Local JSON sync is included in every paid plan.

Local JSON Sync — Git-Friendly Field Groups