Watch asset directories for changes during dev

[melissaluu]

WHY are these changes introduced?

Closes https://github.com/shop/issues-admin-extensibility/issues/2461

When developers add new files to the watched assets directories during a dev sesstion, they were not being picked up by the file watcher and meant that adding an asset image would not trigger a rebuild or hot-reload.

WHAT is this pull request doing?

Introduces a mechanism for ExtensionInstance to track additional watched paths beyond its source imports, and wires it into the file watcher and build pipeline:

• Adds addWatchedPath, getWatchedPaths, and clearWatchedPaths methods to ExtensionInstance. Paths are stored in a deduplicated Set and are included in the output of watchedFiles().
• In executeIncludeAssetsStep, directory-type asset sources are registered as watched paths on the extension after being copied, so the watcher knows to monitor them.
• In FileWatcher, the extensionWatchedFiles map now tracks both files and directories. A new getExtensionHandlesForFilePath method resolves the owning extension for any file path by checking both exact matches and prefix matches against watched directories. Directories themselves are excluded from the paths passed to chokidar (since chokidar already watches the extension directory), but files inside them are still attributed to the correct extension.
• In AppEventWatcher, after building extensions, the set of watched paths is compared before and after the build. If new paths were registered (e.g., a new asset directory was discovered), the file watcher is restarted to pick them up.

How to test your changes?

Video

1. Create an app-home extension that uses include_assets with a asset config key pointing to a directory.
2. Run shopify app dev.
3. Add a file inside the watched asset directory.
4. Confirm that the change is detected as a new websocket message and triggers the expected rebuild/update.
5. Update the app to show the new image and verify the image is displayed correctly
6. Rename the new file and ensure the app now shows a broken image
7. Rename the file back to the original name and check if the app now shows the correct image again
8. Delete the file and check if the app shows the broken image

Checklist

• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've considered possible documentation changes
• I've considered analytics changes to measure impact
• The change is user-facing — I've identified the correct bump type (patch for bug fixes · minor for new features · major for breaking changes) and added a changeset with pnpm changeset addgeeck

[melissaluu]

• Watch asset directories for changes during dev #7470 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[melissaluu]

Added this to enable deleting an asset will emit a websocket update event.

Without it, since the shouldIgnoreEvent() calls extension.watchedFiles() which runs globSync live against the filesystem. For delete events, by the time this check runs, the file is already gone from disk — so globSync never returns it, isAValidWatchedPath is false, and the event gets silently dropped.

[melissaluu]

/snapit

[github-actions]

🫰✨ Thanks @melissaluu! Your snapshot has been published to npm.

Test the snapshot by installing your package globally:

pnpm i -g --@shopify:registry=https://registry.npmjs.org @shopify/cli@0.0.0-snapshot-20260506213108

Caution

After installing, validate the version by running shopify version in your terminal.
If the versions don't match, you might have multiple global instances installed.
Use which shopify to find out which one you are running and uninstall it.