Local JSON Sync saves your field group definitions as JSON files inside your theme folder. This feature exists primarily for development workflows where a developer uses version control (like Git) to manage code changes and deploy them across environments (local machine, staging server, production server). For most content managers, this feature runs silently in the background and requires no action beyond occasionally clicking a “Sync” button.
Do not confuse this with ACF’s Local JSON folder. Field Forge writes its own files to fieldforge-json/ by default. During migration from ACF, Field Forge can also read ACF’s acf-json/group_*.json files as a source when no ACF field-group database records exist.
This section explains what JSON Sync does, why it exists, when you might encounter it, and what to do when you see sync notifications in the admin.
Why Local JSON Sync Exists
When a developer builds a site, they typically create field groups on their local machine. Without JSON Sync, field group definitions live only in the database. To move them to the staging or production server, the developer would have to manually export and import JSON files every time they make a change. JSON Sync automates this by writing field group definitions to files inside the theme folder. These files travel with the theme code through version control, and when the code is deployed, Field Forge detects the new or changed files and applies them.
This workflow is invisible to content managers — the fields just appear or update as the developer pushes changes.
How It Works Behind the Scenes
- When JSON Sync is enabled, every time a field group is saved in the admin, Field Forge writes a JSON file to
fieldforge-json/inside the active theme (the default folder name; override via thefieldforge/local_json/save_pathfilter) - The JSON file contains the complete field group definition: fields, types, settings, layout, location rules, conditional logic, and order
- The developer includes these files in their version control repository (Git, SVN, etc.)
- When updated files are deployed to a server, Field Forge detects that the JSON files are newer than the database versions
- A sync notice appears in the admin prompting you to apply the updates
What Content Managers Need to Know
Most of the time, JSON Sync works invisibly. Here are the two situations where you might need to take action:
Situation 1: You see a “field groups out of sync” notification- Go to Field Forge > Field Groups
- You will see a banner or badge indicating that one or more field groups are out of sync with their JSON files
- Click the Sync button
- Field Forge updates the database field groups to match the JSON files
- The notification disappears
- This means your developer pushed changes — the updated fields now reflect their work
If you edit a field group in the admin while JSON Sync is enabled, your changes are saved to the database AND written to the JSON file in the theme. If a developer later pushes their own version of that JSON file, there could be a conflict.
| Scenario | What Happens |
|---|---|
| Only the developer changed the JSON file | Sync applies their changes cleanly when you click Sync |
| Only you changed the field group in the admin | Your changes are live. The JSON file was updated with your changes. If the developer pulls your updated JSON file, they see your changes. |
| Both you and the developer changed the same field group | Field Forge detects a conflict and shows a warning. You choose which version to keep. |
Enabling or Disabling JSON Sync
- Go to Field Forge > Settings
- Find the Local JSON Sync toggle
- Turn it on or off
- The save path is
fieldforge-json/inside the active theme folder. There is no UI control for this — your developer can override the path via thefieldforge/local_json/save_pathfilter if they need a custom location. - Save settings
Key Details About JSON Files
- JSON files are plain text containing only the field group structure — they do not contain any post content, editor data, user information, or media files
- Saving a field group with sync enabled writes the corresponding JSON file immediately
- Deleting a field group also deletes its JSON file
- The sync folder path can be customized by your developer if they use a non-standard folder structure
- JSON Sync works with any version control system (Git, SVN, Mercurial, etc.)
- If you switch themes, the JSON files in the old theme’s folder are no longer detected. Your developer may need to move or copy them.
Communication Tips for Teams Using JSON Sync
If you work closely with a developer who uses JSON Sync:
- Communicate before editing field groups in the admin. If the developer is also working on field group changes in their code, simultaneous edits create conflicts.
- Let the developer know when you add or remove fields. They may need to update theme templates to display new fields or remove references to deleted ones.
- When you see a sync notification, click Sync promptly. Delaying the sync means your database has stale field definitions while the JSON files have the latest version. This can cause confusion if you edit a field group in the meantime.
> Good to know: If you are a content manager who never works with theme files or version control, you can safely ignore this feature entirely. It runs silently if your developer enabled it. The only time you need to do anything is when a sync notification appears — just click the Sync button and you are done.
> Tip: If you accidentally make changes to a field group and want the developer’s version instead, use the Sync feature to overwrite your changes with the JSON file version. Conversely, if you want your changes to stick, save the field group in the admin — the JSON file updates to match your version.
—