Double browser reload when using external build tool (esbuild) with assets.folder

[schalkneethling]

Description

When using miyagi with an external build tool (esbuild) that watches source files and outputs to a folder configured in assets.folder, miyagi triggers two browser reloads for every file change instead of one.

Environment

• miyagi version: 4.x (with Twing)
• Node.js: 24.1.0
• OS: macOS

Setup

Our project has:

• Source files: src/components/ (templates, mocks, CSS, JS)
• Build output: build/assets/ (esbuild bundles CSS/JS here)
• miyagi config:

assets: {
  css: ['build/assets/css/common.css', ...],
  js: [{src: 'build/assets/js/common.js', type: 'module'}, ...],
  folder: ['src/fonts', 'build/assets'],
},
components: {
  folder: 'src/components',
}

We run miyagi start and esbuild --watch in parallel.

Steps to Reproduce

1. Configure miyagi with assets.folder pointing to esbuild's output directory
2. Run miyagi and esbuild watch mode in parallel
3. Edit a CSS file in src/components/
4. Observe terminal output

Expected Behavior

One browser reload after the file change is processed.

Actual Behavior

Two browser reloads occur:

1. First reload when miyagi detects the source file change in src/components/
2. Second reload ~1-5 seconds later when miyagi detects esbuild's output in build/assets/

Terminal output shows:

A file has been changed, miyagi is updating the state.
[watch] build started (change: "src/components/.../file.css")
[watch] build finished
A file has been changed, miyagi is updating the state.  <-- second detection
Reloading browser window!
Updating done!
Reloading browser window!  <-- second reload
Updating done!

Root Cause Analysis

Looking at lib/init/watcher.js, miyagi watches:

const foldersToWatch = [
  ...assets.folder.map((f) => path.join(global.config.assets.root, f)),
  ...assets.css...,
  ...assets.js...,
];

if (components.folder) {
  foldersToWatch.push(components.folder);
}

Both src/components AND build/assets are watched. When a source file changes:

1. miyagi detects it → triggers reload
2. esbuild rebuilds to build/assets/
3. miyagi detects the build output → triggers another reload

The components.ignores filter doesn't help because:

1. It only accepts strings (functions cause sanitizePath.startsWith is not a function error)
2. Glob patterns like ** cause regex errors
3. Simple strings don't match full paths properly with anymatch

Suggested Solutions

Option 1: Separate "serve" from "watch"

Add a config option to serve static files WITHOUT watching them:

assets: {
  folder: ['build/assets'],
  watchFolder: false,  // NEW: serve but don't watch
}

Option 2: Add watchIgnores config

Add a dedicated ignore pattern for the watcher that supports globs/functions:

watcher: {
  ignores: ['**/build/**'],  // or: (path) => path.includes('/build/')
}

Option 3: File type filtering for components folder

Allow specifying which file types to watch in the components folder:

components: {
  folder: 'src/components',
  watchPatterns: ['**/*.twig', '**/*.yaml', '**/*.md'],  // Only watch these
}

Option 4: Increase debounce timeout

The current 10ms debounce in the watcher is too short to batch the source change with the build output change. Increasing it to ~1000-1500ms would help, though this is a workaround rather than a fix.

Additional Issue: Spurious "Updating configuration" events

During debugging, we also observed multiple "Updating configuration..." messages even when only component files were changed (not .miyagi.js). This appears to be related to fs.watch emitting spurious events on macOS. The config file watcher might benefit from debouncing or using a more robust file watching approach.

Workaround Attempts That Failed

1. Adding "build" or "build/assets" to components.ignores - doesn't match paths correctly
2. Using glob patterns like "**/build/**" - causes regex errors
3. Using functions in ignores - causes sanitizePath.startsWith is not a function

---

Happy to provide more details or help with a fix. This is a common setup for projects that use bundlers alongside miyagi.

[schalkneethling]

Additional Context: Multiple esbuild Watch Processes

I should clarify our build setup more precisely. The start script runs:

"start:assets": "run-p build:copy 'build:msw --watch' 'build:css -- --watch' 'build:js -- --watch'",
"start:cl": "miyagi start",
"start": "run-p start:assets start:cl",

This means we have THREE separate esbuild watch processes running in parallel, all outputting to build/assets/:

Process	Watches	Outputs to
build:msw --watch	src/msw/*.js	build/assets/msw/
build:css --watch	src/css/*.css (+ imports from components)	build/assets/css/
build:js --watch	src/js/*.js (+ imports)	build/assets/js/

The CSS bundle (common.css) imports component CSS files via:

/* src/css/common.css */
@import "../components/elements/elements.css" layer(components);
/* which imports */
@import url("./button/button.css");
/* etc. */

So when I edit src/components/elements/button/button.css:

1. Miyagi detects source file change in src/components/ → triggers reload Bump lodash.template from 4.4.0 to 4.5.0 #1
2. esbuild css watcher detects change (via import chain) → rebuilds build/assets/css/common.css + common.css.map
3. Miyagi detects build/assets/css/ change → triggers reload Bump lodash from 4.17.11 to 4.17.14 #2

The Architectural Conflict

The fundamental issue is that both miyagi AND esbuild are watching the same source files:

• Miyagi watches src/components/ for templates, mocks, AND CSS/JS
• esbuild watches src/css/ which imports from src/components/

With the current miyagi architecture, there's no way to tell miyagi: "watch src/components/ for .twig, .yaml, .md files only, and let esbuild handle CSS/JS."

The ui.reloadAfterChanges.componentAssets: false setting prevents reload for component CSS/JS changes, but miyagi still watches assets.folder (where esbuild outputs), causing the second reload.

[schalkneethling]

Here is the terminal output after hacing just run yarn start inside the component library folder:

2025/12/07 21:11:02 Error: Port 5000 already in use, trying to find a free port…
2025/12/07 21:11:02 Success: Running miyagi server at http://localhost:5001

2025/12/07 21:11:03 Info: Updating configuration…
2025/12/07 21:11:03 Info: Updating configuration…
2025/12/07 21:11:03 Success: Reloading browser window! (1)

2025/12/07 21:11:03 Success: Updating done!

2025/12/07 21:11:03 Success: Reloading browser window! (2)

2025/12/07 21:11:03 Success: Updating done!

2025/12/07 21:11:08 Info: Updating configuration…
2025/12/07 21:11:08 Success: Reloading browser window! (3)

2025/12/07 21:11:08 Success: Updating done!