When I first encountered the task of syncing Gutenberg template parts with actual theme files, I realized: the usual approach through the WordPress database isn’t always convenient.

You edit a block in the editor — but nothing changes in the theme files. Manual code editing? No, thanks. I needed a Gutenberg Sync that works automatically while remaining highly flexible.

In this article, I’ll explain how I created the Gutenberg Sync plugin, what it does, and how it works at a high level — without diving too deep technically, but with clear logic.

Why You Need Gutenberg Sync

The main problem developers and agencies face: you change a header, footer, or section in the block editor, but all changes remain only in the WordPress database.

This means:

  • You can’t quickly update a theme file.
  • If someone else works with the code, changes get lost.
  • Any manual edit in the file carries the risk of conflicts.

This is where Gutenberg Sync comes in. The idea is simple: any changes you make to template parts in the editor are saved automatically or manually to the corresponding theme HTML files.

How the Plugin Works

I split the functionality into two levels:

1. Manual Block Sync

In the editor, a “Sync to file” button appears next to each template part. Clicking it saves exactly the block you’re editing directly to the theme file.

Internally, it works like this:

  • A React script gets the block’s clientId and its attributes.
  • All nested blocks inside the selected template part are serialized.
  • The content is sent to the server via the plugin’s REST API.
  • PHP checks if the file exists in the parts or templates folders.
  • If the file exists — the content is updated; if not — a notification appears.

This way, you always know that the block you edit in the editor matches the theme file exactly.

2. Automatic Sync on Save

To avoid thinking about each click, I added auto-sync:

  • When saving a post or page, the plugin iterates through all template-part blocks on the page.
  • Each block is serialized and sent to the file.
  • Everything happens quietly in the background, with only console notifications (for debugging).

This allows you to edit in Gutenberg while keeping your theme files always up to date.

Supported Folders

To avoid touching the entire theme code, the plugin only works with specific folders:

  • parts — headers, footers, sections
  • templates — pages and content templates

Any file outside these folders is ignored. This reduces the risk of accidentally overwriting important code.

How I Implemented Sync

From a code perspective, everything revolves around two parts:

  • PHP — REST API for reading and writing files. It checks if a file exists, writes content, and returns a result. Everything is secure: permissions are checked via current_user_can('edit_posts').
  • JavaScript / React — adds the button in the Gutenberg editor. WordPress hooks (addFilter) and select from @wordpress/data are used to fetch blocks. Important: only nested blocks of the selected template part are serialized to avoid saving unnecessary content.

Additionally, there are debug logs to help verify that the script is loaded and the sync is running.

Who Needs This Plugin

  • Agencies building sites with Gutenberg blocks.
  • Anyone actively using template parts and wanting to work directly with theme files.
  • Developers who need changes in the editor to immediately reflect in code.

It’s perfect for modern themes where block structures are well-thought-out and fast sync with files is required.

Summary

When creating Gutenberg Sync, I aimed to solve three goals:

  • Make working with templates convenient and transparent.
  • Eliminate manual file editing for each change.
  • Provide automatic sync on page save.

Now the plugin allows you to:

  • Save changes to a specific block manually.
  • Automatically update all template-part blocks on save.
  • Work with specific theme folders without touching extra code.

If you use Gutenberg and want full control over your templates, Gutenberg Sync is the perfect tool to synchronize the editor with template files in your block-based WordPress theme.

https://github.com/ecomsys/ecomsys-parts-sync