Hook app asset file watcher into the existing app event watcher list and fix upload assets on change

Co-authored-by: Trish Ta <trish.ta@shopify.com>

Author: melissaluu

packages/app/src/cli/models/extensions/specifications/admin.ts

@@ -3,6 +3,7 @@ import {createContractBasedModuleSpecification} from '../specification.js'
 const adminSpecificationSpec = createContractBasedModuleSpecification({
   identifier: 'admin',
   uidStrategy: 'single',
+  experience: 'configuration',
   transformRemoteToLocal: (remoteContent) => {
     return {
       admin: {
@@ -24,7 +25,8 @@ const adminSpecificationSpec = createContractBasedModuleSpecification({
           name: 'Hosted App Copy Files',
           type: 'include_assets',
           config: {
-            generatesAssetsManifest: true,
+            // Remove this until we fix the bug related to recreating the manifest during dev
+            generatesAssetsManifest: false,
             inclusions: [
               {
                 type: 'configKey',

packages/app/src/cli/services/dev/app-events/app-event-watcher-handler.ts

@@ -32,6 +32,7 @@ export async function handleWatcherEvents(
     const affectedExtensions = app.realExtensions.filter((ext) => ext.directory === event.extensionPath)
     const newEvent = handlers[event.type]({event, app: appEvent.app, extensions: affectedExtensions, options})
     appEvent.extensionEvents.push(...newEvent.extensionEvents)
+    if (newEvent.appAssetsUpdated) appEvent.appAssetsUpdated = true
   }
 
   return appEvent
@@ -61,6 +62,7 @@ const handlers: {[key in WatcherEvent['type']]: Handler} = {
   file_deleted: FileChangeHandler,
   file_updated: FileChangeHandler,
   app_config_deleted: AppConfigDeletedHandler,
+  app_asset_updated: AppAssetUpdatedHandler,
   // These two are processed manually to avoid multiple reloads
   extension_folder_created: EmptyHandler,
   extensions_config_updated: EmptyHandler,
@@ -91,6 +93,17 @@ function FileChangeHandler({event, app, extensions}: HandlerInput): AppEvent {
   return {app, extensionEvents: events, startTime: event.startTime, path: event.path}
 }
 
+/**
+ * When a file inside an app asset directory (e.g. static_root) is updated:
+ * Find the owning extension via extensionPath and return an Updated event so it gets rebuilt.
+ * The rebuild runs the include_assets step which copies the changed files into the bundle.
+ */
+function AppAssetUpdatedHandler({event, app}: HandlerInput): AppEvent {
+  const adminExtension = app.realExtensions.find((ext) => ext.specification.identifier === 'admin')
+  const events: ExtensionEvent[] = adminExtension ? [{type: EventType.Updated, extension: adminExtension}] : []
+  return {app, extensionEvents: events, startTime: event.startTime, path: event.path, appAssetsUpdated: true}
+}
+
 /**
  * When an event doesn't require any action, return the same app and an empty event.
  */

packages/app/src/cli/services/dev/app-events/app-event-watcher.ts

@@ -82,6 +82,7 @@ export interface AppEvent {
   path: string
   startTime: [number, number]
   appWasReloaded?: boolean
+  appAssetsUpdated?: boolean
 }
 
 type ExtensionBuildResult = {status: 'ok'; uid: string} | {status: 'error'; error: string; file?: string; uid: string}

packages/app/src/cli/services/dev/app-events/file-watcher.test.ts

@@ -263,15 +263,15 @@ describe('file-watcher events', () => {
 
       // Then
       expect(watchSpy).toHaveBeenCalledWith([joinPath(dir, '/shopify.app.toml'), joinPath(dir, '/extensions')], {
-        ignored: [
+        ignored: expect.arrayContaining([
           '**/node_modules/**',
           '**/.git/**',
           '**/*.test.*',
-          '**/dist/**',
           '**/*.swp',
           '**/generated/**',
           '**/.gitignore',
-        ],
+          expect.any(Function),
+        ]),
         ignoreInitial: true,
         persistent: true,
       })

packages/app/src/cli/services/dev/app-events/file-watcher.ts

@@ -1,6 +1,7 @@
 /* eslint-disable no-case-declarations */
 import {AppLinkedInterface} from '../../../models/app/app.js'
 import {configurationFileNames} from '../../../constants.js'
+import {ExtensionInstance} from '../../../models/extensions/extension-instance.js'
 import {dirname, joinPath, normalizePath, relativePath} from '@shopify/cli-kit/node/path'
 import {FSWatcher} from 'chokidar'
 import {outputDebug} from '@shopify/cli-kit/node/output'
@@ -9,6 +10,7 @@ import {startHRTime, StartTime} from '@shopify/cli-kit/node/hrtime'
 import {fileExistsSync, matchGlob, mkdir, readFileSync} from '@shopify/cli-kit/node/fs'
 import {debounce} from '@shopify/cli-kit/common/function'
 import ignore from 'ignore'
+import {getPathValue} from '@shopify/cli-kit/common/object'
 import {Writable} from 'stream'
 
 const DEFAULT_DEBOUNCE_TIME_IN_MS = 200
@@ -36,6 +38,7 @@ export interface WatcherEvent {
     | 'file_deleted'
     | 'extensions_config_updated'
     | 'app_config_deleted'
+    | 'app_asset_updated'
   path: string
   extensionPath: string
   startTime: StartTime
@@ -58,6 +61,8 @@ export class FileWatcher {
   private readonly ignored: {[key: string]: ignore.Ignore | undefined} = {}
   // Map of file paths to the extensions that watch them
   private readonly extensionWatchedFiles = new Map<string, Set<string>>()
+  // Map of asset directory path to the extension directory that owns it
+  private appAssetToExtensionDir = new Map<string, string>()
 
   constructor(
     app: AppLinkedInterface,
@@ -104,7 +109,9 @@ export class FileWatcher {
       }),
     )
 
+    this.appAssetToExtensionDir = this.resolveAppAssetWatchPaths(this.app.realExtensions)
     const watchPaths = [this.app.configPath, ...fullExtensionDirectories]
+    Array.from(this.appAssetToExtensionDir.keys()).forEach((key) => watchPaths.push(key))
 
     // Get all watched files from extensions
     const allWatchedFiles = this.getAllWatchedFiles()
@@ -114,15 +121,24 @@ export class FileWatcher {
 
     // Create new watcher
     const {default: chokidar} = await import('chokidar')
+    const appAssetDirs = [...this.appAssetToExtensionDir.keys()]
     this.watcher = chokidar.watch(watchPaths, {
       ignored: [
         '**/node_modules/**',
         '**/.git/**',
         '**/*.test.*',
-        '**/dist/**',
         '**/*.swp',
         '**/generated/**',
         '**/.gitignore',
+        // Ignore files inside dist/ directories, unless the path falls under a watched
+        // app asset directory (e.g. static_root may point to a dist/ folder).
+        // Non-dist paths are never ignored here (return false). For dist paths, we only
+        // allow them through if they are inside one of the app asset directories.
+        (filePath: string) => {
+          const normalized = normalizePath(filePath)
+          if (!normalized.includes('/dist/') && !normalized.endsWith('/dist')) return false
+          return !appAssetDirs.some((assetDir) => normalized.startsWith(assetDir))
+        },
       ],
       persistent: true,
       ignoreInitial: true,
@@ -177,6 +193,36 @@ export class FileWatcher {
     return Array.from(allFiles)
   }
 
+  /**
+   * Resolves app asset directories that should be watched.
+   * Returns a map of absolute asset directory path → owning extension directory.
+   */
+  private resolveAppAssetWatchPaths(allExtensions: ExtensionInstance[]): Map<string, string> {
+    const result = new Map<string, string>()
+    const adminExtension = allExtensions.find((ext) => ext.specification.identifier === 'admin')
+    if (adminExtension) {
+      const staticRootPath = getPathValue<string>(adminExtension.configuration, 'admin.static_root')
+      if (staticRootPath) {
+        const absolutePath = joinPath(adminExtension.directory, staticRootPath)
+        result.set(normalizePath(absolutePath), normalizePath(adminExtension.directory))
+      }
+    }
+    return result
+  }
+
+  /**
+   * Checks if a file path is inside any app asset directory.
+   * Returns the owning extension directory if found, undefined otherwise.
+   */
+  private findAppAssetExtensionDir(filePath: string): string | undefined {
+    for (const [assetDir, extensionDir] of this.appAssetToExtensionDir) {
+      if (filePath.startsWith(assetDir)) {
+        return extensionDir
+      }
+    }
+    return undefined
+  }
+
   /**
    * Emits the accumulated events and resets the current events list.
    * It also logs the number of events emitted and their paths for debugging purposes.
@@ -227,7 +273,12 @@ export class FileWatcher {
    * Explicit watch paths have priority over custom gitignore files
    */
   private shouldIgnoreEvent(event: WatcherEvent) {
-    if (event.type === 'extension_folder_deleted' || event.type === 'extension_folder_created') return false
+    if (
+      event.type === 'extension_folder_deleted' ||
+      event.type === 'extension_folder_created' ||
+      event.type === 'app_asset_updated'
+    )
+      return false
 
     const extension = this.app.realExtensions.find((ext) => ext.directory === event.extensionPath)
     const watchPaths = extension?.watchedFiles()
@@ -258,6 +309,16 @@ export class FileWatcher {
       const affectedExtensions = this.extensionWatchedFiles.get(normalizedPath)
       const isUnknownExtension = affectedExtensions === undefined || affectedExtensions.size === 0
 
+      // Check if the file is inside an app asset directory (e.g. static_root)
+      const appAssetExtensionDir = this.findAppAssetExtensionDir(normalizedPath)
+      if (appAssetExtensionDir) {
+        if (event === 'change' || event === 'add' || event === 'unlink') {
+          this.pushEvent({type: 'app_asset_updated', path, extensionPath: appAssetExtensionDir, startTime})
+        }
+        this.debouncedEmit()
+        return
+      }
+
       if (isUnknownExtension && !isExtensionToml && !isConfigAppPath) {
         // Ignore an event if it's not part of an existing extension
         // Except if it is a toml file (either app config or extension config)

packages/app/src/cli/services/dev/extension.ts

@@ -13,10 +13,8 @@ import {AbortSignal} from '@shopify/cli-kit/node/abort'
 import {outputDebug} from '@shopify/cli-kit/node/output'
 import {joinPath} from '@shopify/cli-kit/node/path'
 import {getPathValue} from '@shopify/cli-kit/common/object'
-import {fileExists} from '@shopify/cli-kit/node/fs'
 import {DotEnvFile} from '@shopify/cli-kit/node/dot-env'
 import {Writable} from 'stream'
-import type {FSWatcher} from 'chokidar'
 
 interface AppAssets {
   [key: string]: string
@@ -170,64 +168,16 @@ export async function devUIExtensions(options: ExtensionDevOptions): Promise<voi
   const websocketConnection = setupWebsocketConnection({...payloadOptions, httpServer, payloadStore})
   outputDebug(`Setting up the UI extensions bundler and file watching...`, payloadOptions.stdout)
 
-  // Set up asset directory watchers
-  let assetWatchers: FSWatcher[] = []
-  const debounceTimers = new Map<string, ReturnType<typeof setTimeout>>()
-
-  function createDebouncedAssetUpdater(assetKey: string) {
-    return () => {
-      const existing = debounceTimers.get(assetKey)
-      if (existing) clearTimeout(existing)
-      debounceTimers.set(
-        assetKey,
-        setTimeout(() => {
-          debounceTimers.delete(assetKey)
-          payloadStore.updateAppAssetTimestamp(assetKey)
-        }, 200),
-      )
-    }
-  }
-
-  function clearDebounceTimers() {
-    for (const timer of debounceTimers.values()) {
-      clearTimeout(timer)
-    }
-    debounceTimers.clear()
-  }
-
-  async function startAssetWatchers(assets: Record<string, string>) {
-    // Clear pending debounce timers and close existing watchers
-    clearDebounceTimers()
-    await Promise.all(assetWatchers.map((watcher) => watcher.close()))
-    // eslint-disable-next-line require-atomic-updates
-    assetWatchers = []
-
-    const {default: chokidar} = await import('chokidar')
-    for (const [assetKey, directoryPath] of Object.entries(assets)) {
-      const exists = await fileExists(directoryPath)
-      if (!exists) continue
-
-      const watcher = chokidar.watch(directoryPath, {ignoreInitial: true})
-      watcher.on('all', createDebouncedAssetUpdater(assetKey))
-      assetWatchers.push(watcher)
-    }
-  }
-
-  const initialAppAssets = payloadOptions.appAssets
-  if (initialAppAssets && Object.keys(initialAppAssets).length > 0) {
-    await startAssetWatchers(initialAppAssets)
-  }
-
-  const eventHandler = async ({appWasReloaded, app, extensionEvents}: AppEvent) => {
+  const eventHandler = async ({appWasReloaded, app, extensionEvents, appAssetsUpdated}: AppEvent) => {
     if (appWasReloaded) {
       extensions = app.allExtensions.filter((ext) => ext.isPreviewable)
+    }
 
-      // Re-resolve app assets in case admin extension was added/removed/changed
-      const newAppAssets = resolveAppAssets(app.allExtensions)
-      const hasAssets = Object.keys(newAppAssets).length > 0
-      payloadOptions.appAssets = hasAssets ? newAppAssets : undefined
-      payloadStore.updateAppAssets(payloadOptions.appAssets, payloadOptions.url)
-      await startAssetWatchers(hasAssets ? newAppAssets : {})
+    if (appAssetsUpdated && payloadOptions.appAssets) {
+      for (const assetKey of Object.keys(payloadOptions.appAssets)) {
+        payloadStore.updateAppAssetTimestamp(assetKey)
+      }
+      return
     }
 
     for (const event of extensionEvents) {
@@ -264,10 +214,6 @@ export async function devUIExtensions(options: ExtensionDevOptions): Promise<voi
 
   payloadOptions.signal.addEventListener('abort', () => {
     outputDebug('Closing the UI extensions dev server...')
-    clearDebounceTimers()
-    for (const watcher of assetWatchers) {
-      watcher.close().catch(() => {})
-    }
     websocketConnection.close()
     httpServer.close()
   })