Web

Fix Gutenberg block JS not updating during npm start

Fix Gutenberg block JS not updating in the editor. Edit src/, keep npm start running, run npm run build if needed, hard-refresh and clear browser/server caches.

1 answer• 1 view

Custom Gutenberg block created with @wordpress/create-block: my JavaScript changes are not reflected in the WordPress editor after running npm start on a local XAMPP setup. What steps should I take to ensure edits update immediately — do I need to clear caches, rebuild assets, restart the dev server, re-activate the plugin, or perform other actions?

For a Gutenberg block created with @wordpress/create-block, edit the source files under src/, keep npm run start running (watch the terminal for rebuilds), and confirm the editor is loading the dev-server bundle. If edits still don’t appear, hard-refresh and disable browser cache, check the Network/Console to see which JS file is actually loaded, run npm run build to write disk files if necessary, restart the dev server, and clear any server/PHP caches (OPcache) or WP caching layers — only rarely is plugin re-activation required.

Contents

Quick checklist to refresh a Gutenberg block

  • Edit files in src/ (not build/).
  • Keep npm run start running and watch its terminal for successful rebuilds.
  • Hard-reload the editor (Ctrl/Cmd+Shift+R) or disable cache in DevTools.
  • Inspect Network/Console to confirm which bundle the editor actually loads.
  • If the dev server uses an in-memory build, run npm run build to write files to disk.
  • If nothing helps, restart the dev server, restart Apache/PHP (XAMPP), and clear server caches (including OPCache).

These are the fastest checks to do before deeper debugging.

Edit the right files for your Gutenberg block (src vs build)

Most developers accidentally edit build/index.js (the generated bundle). That file is overwritten by the build system. Always change the source in src/ (e.g., src/index.js, src/edit.js) and let the tooling rebuild.

Why? @wordpress/create-block scaffolds a source tree where src/ is the editable React/JSX source and build/ is the compiled output. The dev server/watch process rewrites build/ as you save, so edits to build/ are temporary and will be replaced. See the Block Editor handbook for the recommended workflow: https://developer.wordpress.org/block-editor/getting-started/devenv/get-started-with-create-block/

How npm start (dev server) should update your Gutenberg block

npm run start launches a development server (webpack dev server via @wordpress/scripts) that watches src/ and rebuilds on change. Watch its terminal: when you save a file you should see compilation messages. If nothing appears in the terminal, the watcher may have crashed or not be running.

Two gotchas to watch for:

  • The dev server can serve assets from memory (not write them to disk). If WordPress is loading the plugin’s on-disk build/ files instead of the dev server URL, edits won’t appear in the editor. Inspect the script URL in DevTools (Network tab) to see if the editor is requesting http://localhost:8080/... (dev server) or /wp-content/plugins/your-plugin/build/index.js (disk).
  • Mixed-content or CORS: if your WordPress site is served over HTTPS and the dev server uses HTTP, the browser may block the dev bundle. Check the Console for blocked requests.

If npm start shows errors during compilation (PostCSS, Babel, etc.), those will prevent updated assets from being served — fix build errors shown in the terminal.

See a related community report where the dev server rebuilds but the editor still didn’t show changes: https://github.com/WordPress/gutenberg/issues/23139

When to run npm run build and (re)activate the plugin

  • Use npm run start for active development and hot rebuilds.
  • Use npm run build when you want a production bundle written to disk (or when your dev server doesn’t write to disk).

If your editor is loading the on-disk build (not the dev server), running npm run build will update those files immediately. In most cases you do NOT need to deactivate and reactivate the plugin — WordPress reads the build files on each request. Re-activating can help only if your plugin stores asset metadata on activation (rare for create-block scaffolds) or if some plugin code runs once at activation to generate files. Some users reported re-activating fixed stale assets, but try build + hard reload first.

Reference: community troubleshooting showing rebuild + wp-env restart fixed visibility: https://stackoverflow.com/questions/78564902/wordpress-block-not-showing-after-npx-wordpress-create-blocklatest-and-activ

Clear caches that commonly hide JS changes

Caching can mask fresh bundles at several layers:

  • Browser cache: hard refresh or disable cache in DevTools.
  • Caching plugins / page caches (WP Super Cache, W3 Total Cache): temporarily disable and purge. See WordPress support discussions: https://wordpress.org/support/topic/caching-issue-with-gutenberg/
  • Server caches / CDNs: purge if you use one.
  • PHP OPcache: if XAMPP’s OPcache has validate_timestamps=0 you may need to restart Apache or PHP-FPM to pick up new files. Restart the XAMPP Apache service to be safe.
  • Object cache (Redis, Memcached): flush if script URLs or metadata are cached.

A quick test: open DevTools → Network → click the script URL for your block and check its timestamp/content. That tells you whether the browser is getting the new bundle.

Editor iframe and asset-injection edge cases

The block editor renders content in an iframe context (editor-canvas). There are known cases where dev-server CSS/JS updates appear in the main document head but not inside the editor iframe — see https://github.com/WordPress/gutenberg/issues/48448. If you notice CSS updates but not the editor appearance, check the iframe’s head (Elements panel → select iframe document) and the Network tab scoped to the iframe.

If your block relies on additional JS files that assume a parent window context, they may fail inside the editor iframe (see https://github.com/WordPress/gutenberg/issues/31022). In those cases adjust the script to be iframe-safe or load a wrapper that targets the editor context.

Check versions, build errors and @wordpress/scripts

Sometimes a tooling bug or mismatched @wordpress/scripts version causes dev-server behavior to break. If npm start rebuilds but the editor shows no change:

Practical step-by-step debugging checklist (do these now)

  1. Stop and restart npm run start. Watch its output while you save a test change.
  2. In your plugin folder: edit src/index.js (not build/index.js) and save.
  3. Open the browser DevTools → Console and Terminal where npm start runs. Look for compile success or errors.
  4. In DevTools → Network filter by .js and find the block bundle. Confirm the URL — is it localhost:8080 or your plugin build/ path?
  5. If the bundle is served from disk, run npm run build and reload the editor.
  6. If the bundle is served from dev server but changes don’t appear, check for mixed-content or CORS errors in Console.
  7. Hard refresh (Ctrl/Cmd+Shift+R) and disable cache.
  8. Restart Apache/PHP (XAMPP) to clear OPcache if you suspect server-side caching.
  9. Disable any caching plugins and purge caches.
  10. If you still see stale code, try re-activating the plugin (rarely needed) and check block.json / index.asset.php timestamps.

Want a quick pointer on what to look for in Network? Open the script request and compare the response body to your local changes — that immediately tells you whether WordPress loaded the updated file.

Alternatives and developer tips

  • Use wp-env for an integrated WordPress + block dev environment where npm run start and WordPress coexist more predictably (see the Block Editor Handbook link above).
  • If your dev server serves from memory only, configure webpack to write files to disk (devServer.writeToDisk) or use npm run build frequently.
  • If you prefer avoiding the build step, see blog posts about writing Gutenberg blocks without the build pipeline (for small experiments): https://mkaz.blog/wordpress/gutenberg-blocks-without-the-build-step

Sources

Conclusion

For a create block workflow, the fastest fixes are: edit src/ (not build/), keep npm run start running (watch for rebuilds), confirm the editor loads the dev-server bundle (or run npm run build to write disk files), hard-refresh the editor, and clear browser/server caches (including PHP OPcache). Re-activating the plugin is rarely required — restart the dev server and your XAMPP Apache/PHP if caches persist — and you should see edits update immediately in the Gutenberg editor.

Authors
NeuroAnswers
Author
Verified by moderation
NeuroAnswers
Moderation
Fix Gutenberg block JS not updating during npm start