Add appAssets to the websocket app payload

Author: melissaluu

packages/app/src/cli/models/extensions/specification.ts

@@ -150,6 +150,8 @@ export interface DevSessionWatchConfig {
   paths: string[]
   /** Additional glob patterns to ignore (on top of the default ignore list) */
   ignore?: string[]
+  /** If set, files under these paths are served as app assets under this key (e.g. 'static_root') */
+  assetKey?: string
 }
 
 /**
@@ -446,3 +448,9 @@ export function configWithoutFirstClassFields(config: JsonMapType): JsonMapType
   const {type, handle, uid, path, extensions, ...configWithoutFirstClassFields} = config
   return configWithoutFirstClassFields
 }
+
+// Extracts the base directory from a glob pattern by stripping the glob suffix.
+// e.g. "/app/public/" + glob -> "/app/public"
+export function globPatternBaseDir(pattern: string): string {
+  return pattern.replace(/\/\*.*$/, '')
+}

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

@@ -24,7 +24,7 @@ const adminSpecificationSpec = createExtensionSpecification({
     if (!staticRoot) return {paths: []}
 
     const path = joinPath(extension.directory, staticRoot, '**/*')
-    return {paths: [path], ignore: []}
+    return {paths: [path], ignore: [], assetKey: 'staticRoot'}
   },
   transformRemoteToLocal: (remoteContent) => {
     return {

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

@@ -4,9 +4,11 @@ import {appDiff} from './app-diffing.js'
 import {AppLinkedInterface} from '../../../models/app/app.js'
 import {ExtensionInstance} from '../../../models/extensions/extension-instance.js'
 import {reloadApp} from '../../../models/app/loader.js'
+import {globPatternBaseDir} from '../../../models/extensions/specification.js'
 import {AbortError} from '@shopify/cli-kit/node/error'
 import {endHRTimeInMs, startHRTime} from '@shopify/cli-kit/node/hrtime'
 import {outputDebug} from '@shopify/cli-kit/node/output'
+import {normalizePath} from '@shopify/cli-kit/node/path'
 
 /**
  * Transforms an array of WatcherEvents from the file system into a processed AppEvent.
@@ -32,7 +34,17 @@ export async function handleWatcherEvents(
     const affectedExtensions = event.extensionHandle
       ? app.realExtensions.filter((ext) => ext.handle === event.extensionHandle)
       : app.realExtensions.filter((ext) => ext.directory === event.extensionPath)
-    const newEvent = handlers[event.type]({event, app: appEvent.app, extensions: affectedExtensions, options})
+
+    // Check if this is an app asset change (e.g. file inside admin static_root).
+    // If so, mark assetsUpdated and skip the normal rebuild for those extensions.
+    const assetExtensions = affectedExtensions.filter((ext) => isAppAssetChange(ext, event.path))
+    const nonAssetExtensions = affectedExtensions.filter((ext) => !isAppAssetChange(ext, event.path))
+
+    if (assetExtensions.length > 0) {
+      appEvent.appAssetsUpdated = true
+    }
+
+    const newEvent = handlers[event.type]({event, app: appEvent.app, extensions: nonAssetExtensions, options})
     appEvent.extensionEvents.push(...newEvent.extensionEvents)
   }
 
@@ -125,6 +137,22 @@ async function ReloadAppHandler({event, app}: HandlerInput): Promise<AppEvent> {
   return {app: newApp, extensionEvents, startTime: event.startTime, path: event.path, appWasReloaded: true}
 }
 
+/**
+ * Checks whether a file change is inside an app asset directory (e.g. admin static_root).
+ * App asset changes should only update asset timestamps, not trigger a full extension rebuild.
+ */
+function isAppAssetChange(extension: ExtensionInstance, filePath: string): boolean {
+  if (!extension.isAppConfigExtension) return false
+  const watchConfig = extension.devSessionWatchConfig
+  if (!watchConfig || watchConfig.paths.length === 0 || !watchConfig.assetKey) return false
+
+  const normalizedFile = normalizePath(filePath)
+  return watchConfig.paths.some((pattern) => {
+    const baseDir = normalizePath(globPatternBaseDir(pattern))
+    return normalizedFile.startsWith(baseDir)
+  })
+}
+
 /*
  * Reload the app and returns it
  * Prints the time to reload the app to stdout

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

@@ -83,6 +83,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/extension.test.ts

@@ -1,7 +1,7 @@
 import * as store from './extension/payload/store.js'
 import * as server from './extension/server.js'
 import * as websocket from './extension/websocket.js'
-import {devUIExtensions, ExtensionDevOptions} from './extension.js'
+import {devUIExtensions, ExtensionDevOptions, resolveAppAssets} from './extension.js'
 import {ExtensionsEndpointPayload} from './extension/payload/models.js'
 import {WebsocketConnection} from './extension/websocket/models.js'
 import {AppEventWatcher} from './app-events/app-event-watcher.js'
@@ -65,11 +65,13 @@ describe('devUIExtensions()', () => {
     await devUIExtensions(options)
 
     // THEN
-    expect(server.setupHTTPServer).toHaveBeenCalledWith({
-      devOptions: {...options, websocketURL: 'wss://mock.url/extensions'},
-      payloadStore: {mock: 'payload-store'},
-      getExtensions: expect.any(Function),
-    })
+    expect(server.setupHTTPServer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        devOptions: expect.objectContaining({websocketURL: 'wss://mock.url/extensions'}),
+        payloadStore: expect.objectContaining({mock: 'payload-store'}),
+        getExtensions: expect.any(Function),
+      }),
+    )
   })
 
   test('initializes the HTTP server with a getExtensions function that returns the extensions from the provided options', async () => {
@@ -91,12 +93,13 @@ describe('devUIExtensions()', () => {
     await devUIExtensions(options)
 
     // THEN
-    expect(websocket.setupWebsocketConnection).toHaveBeenCalledWith({
-      ...options,
-      httpServer: expect.objectContaining({mock: 'http-server'}),
-      payloadStore: {mock: 'payload-store'},
-      websocketURL: 'wss://mock.url/extensions',
-    })
+    expect(websocket.setupWebsocketConnection).toHaveBeenCalledWith(
+      expect.objectContaining({
+        httpServer: expect.objectContaining({mock: 'http-server'}),
+        payloadStore: expect.objectContaining({mock: 'payload-store'}),
+        websocketURL: 'wss://mock.url/extensions',
+      }),
+    )
   })
 
   test('closes the http server, websocket and bundler when the process aborts', async () => {
@@ -128,14 +131,87 @@ describe('devUIExtensions()', () => {
     const {getExtensions} = vi.mocked(server.setupHTTPServer).mock.calls[0]![0]
     expect(getExtensions()).toStrictEqual(options.extensions)
 
-    const newUIExtension = {type: 'ui_extension', devUUID: 'BAR', isPreviewable: true}
+    const newUIExtension = {
+      type: 'ui_extension',
+      devUUID: 'BAR',
+      isPreviewable: true,
+      specification: {identifier: 'ui_extension'},
+    }
     const newApp = {
       ...app,
-      allExtensions: [newUIExtension, {type: 'function_extension', devUUID: 'FUNCTION', isPreviewable: false}],
+      allExtensions: [
+        newUIExtension,
+        {
+          type: 'function_extension',
+          devUUID: 'FUNCTION',
+          isPreviewable: false,
+          specification: {identifier: 'function'},
+        },
+      ],
     }
     options.appWatcher.emit('all', {app: newApp, appWasReloaded: true, extensionEvents: []})
 
     // THEN
     expect(getExtensions()).toStrictEqual([newUIExtension])
   })
+
+  test('passes getAppAssets callback to the HTTP server when appAssets provided', async () => {
+    // GIVEN
+    spyOnEverything()
+    const optionsWithAssets = {
+      ...options,
+      appAssets: {staticRoot: '/absolute/path/to/public'},
+    } as unknown as ExtensionDevOptions
+
+    // WHEN
+    await devUIExtensions(optionsWithAssets)
+
+    // THEN
+    expect(server.setupHTTPServer).toHaveBeenCalledWith(
+      expect.objectContaining({
+        getAppAssets: expect.any(Function),
+      }),
+    )
+
+    const {getAppAssets} = vi.mocked(server.setupHTTPServer).mock.calls[0]![0]
+    expect(getAppAssets!()).toStrictEqual({staticRoot: '/absolute/path/to/public'})
+  })
+})
+
+describe('resolveAppAssets()', () => {
+  test('returns empty object when no config extensions have watch paths with assetKey', () => {
+    const extensions = [
+      {isAppConfigExtension: false, devSessionWatchConfig: undefined},
+      {isAppConfigExtension: true, devSessionWatchConfig: {paths: []}},
+      {isAppConfigExtension: true, devSessionWatchConfig: {paths: ['/app/some/**/*']}},
+    ] as unknown as Parameters<typeof resolveAppAssets>[0]
+
+    expect(resolveAppAssets(extensions)).toStrictEqual({})
+  })
+
+  test('returns asset entry keyed by assetKey for config extensions with watch paths', () => {
+    const extensions = [
+      {
+        isAppConfigExtension: true,
+        handle: 'admin',
+        devSessionWatchConfig: {paths: ['/app/public/**/*'], assetKey: 'staticRoot'},
+      },
+    ] as unknown as Parameters<typeof resolveAppAssets>[0]
+
+    expect(resolveAppAssets(extensions)).toStrictEqual({
+      staticRoot: '/app/public',
+    })
+  })
+
+  test('ignores non-config extensions even if they have watch paths with assetKey', () => {
+    const extensions = [
+      {
+        isAppConfigExtension: false,
+        handle: 'ui_ext',
+        devSessionWatchConfig: {paths: ['/app/extensions/ui/**/*'], assetKey: 'assets'},
+      },
+    ] as unknown as Parameters<typeof resolveAppAssets>[0]
+
+    expect(resolveAppAssets(extensions)).toStrictEqual({})
+  })
 })

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

@@ -9,11 +9,17 @@ import {
 import {AppEvent, AppEventWatcher, EventType} from './app-events/app-event-watcher.js'
 import {buildCartURLIfNeeded} from './extension/utilities.js'
 import {ExtensionInstance} from '../../models/extensions/extension-instance.js'
+import {globPatternBaseDir} from '../../models/extensions/specification.js'
 import {AbortSignal} from '@shopify/cli-kit/node/abort'
 import {outputDebug} from '@shopify/cli-kit/node/output'
+import {normalizePath} from '@shopify/cli-kit/node/path'
 import {DotEnvFile} from '@shopify/cli-kit/node/dot-env'
 import {Writable} from 'stream'
 
+interface AppAssets {
+  [key: string]: string
+}
+
 export interface ExtensionDevOptions {
   /**
    * Standard output stream to send the output through.
@@ -112,6 +118,28 @@ export interface ExtensionDevOptions {
    * The app watcher that emits events when the app is updated
    */
   appWatcher: AppEventWatcher
+
+  /**
+   * Map of asset key to absolute directory path for app-level assets (e.g., admin static_root)
+   */
+  appAssets?: AppAssets
+}
+
+/**
+ * Derives app-level asset directories from config extensions that define devSessionWatchConfig
+ * with an assetKey. Returns a map of asset key (e.g. 'static_root') to absolute directory path.
+ */
+export function resolveAppAssets(allExtensions: ExtensionInstance[]): Record<string, string> {
+  const appAssets: Record<string, string> = {}
+  for (const ext of allExtensions) {
+    if (!ext.isAppConfigExtension) continue
+    const watchConfig = ext.devSessionWatchConfig
+    if (!watchConfig || watchConfig.paths.length === 0 || !watchConfig.assetKey) continue
+
+    const baseDir = normalizePath(globPatternBaseDir(watchConfig.paths[0]!))
+    appAssets[watchConfig.assetKey] = baseDir
+  }
+  return appAssets
 }
 
 export async function devUIExtensions(options: ExtensionDevOptions): Promise<void> {
@@ -133,17 +161,29 @@ export async function devUIExtensions(options: ExtensionDevOptions): Promise<voi
   }
 
   outputDebug(`Setting up the UI extensions HTTP server...`, payloadOptions.stdout)
-  const httpServer = setupHTTPServer({devOptions: payloadOptions, payloadStore, getExtensions})
+  const getAppAssets = () => payloadOptions.appAssets
+  const httpServer = setupHTTPServer({
+    devOptions: payloadOptions,
+    payloadStore,
+    getExtensions,
+    getAppAssets,
+  })
 
   outputDebug(`Setting up the UI extensions Websocket server...`, payloadOptions.stdout)
   const websocketConnection = setupWebsocketConnection({...payloadOptions, httpServer, payloadStore})
   outputDebug(`Setting up the UI extensions bundler and file watching...`, payloadOptions.stdout)
 
-  const eventHandler = async ({appWasReloaded, app, extensionEvents}: AppEvent) => {
+  const eventHandler = async ({appWasReloaded, app, extensionEvents, appAssetsUpdated}: AppEvent) => {
     if (appWasReloaded) {
       extensions = app.allExtensions.filter((ext) => ext.isPreviewable)
     }
 
+    if (appAssetsUpdated && payloadOptions.appAssets) {
+      for (const assetKey of Object.keys(payloadOptions.appAssets)) {
+        payloadStore.updateAppAssetTimestamp(assetKey)
+      }
+    }
+
     for (const event of extensionEvents) {
       if (!event.extension.isPreviewable) continue
       const status = event.buildResult?.status === 'ok' ? 'success' : 'error'

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

@@ -8,6 +8,12 @@ interface ExtensionsPayloadInterface {
     url: string
     mobileUrl: string
     title: string
+    assets?: {
+      [key: string]: {
+        url: string
+        lastUpdated: number
+      }
+    }
   }
   appId?: string
   store: string