notify extension dev server of app assets updates

Author: isaacroldan

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

@@ -229,6 +229,7 @@ export interface AppInterface<
   realExtensions: ExtensionInstance[]
   nonConfigExtensions: ExtensionInstance[]
   draftableExtensions: ExtensionInstance[]
+  appAssetsConfigs: Record<string, string> | undefined
   errors: AppErrors
   hiddenConfig: AppHiddenConfig
   includeConfigOnDeploy: boolean | undefined
@@ -334,6 +335,15 @@ export class App<
     )
   }
 
+  get appAssetsConfigs(): Record<string, string> | undefined {
+    if (!this.realExtensions.some((ext) => ext.specification.appAssetsConfig)) return undefined
+    return this.realExtensions.reduce<Record<string, string>>((acc, ext) => {
+      const config = ext.specification.appAssetsConfig?.(ext.configuration)
+      if (config) acc[config.assetsKey] = config.assetsDir
+      return acc
+    }, {})
+  }
+
   setDevApplicationURLs(devApplicationURLs: ApplicationURLs) {
     this.patchAppConfiguration(devApplicationURLs)
     this.realExtensions.forEach((ext) => ext.patchWithAppDevURLs(devApplicationURLs))

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

@@ -143,6 +143,19 @@ export interface ExtensionSpecification<TConfiguration extends BaseConfigType =
    * or undefined to watch all files in the extension directory.
    */
   devSessionWatchConfig?: (extension: ExtensionInstance<TConfiguration>) => DevSessionWatchConfig | undefined
+
+  /**
+   * App assets configuration for this extension.
+   * Return undefined if this extension doesn't serve app assets.
+   */
+  appAssetsConfig?: (config: TConfiguration) => AppAssetsConfig | undefined
+}
+
+export interface AppAssetsConfig {
+  /** The config key that points to the assets directory (e.g. 'admin.static_root') */
+  assetsKey: string
+  /** The assets directory relative to the extension directory */
+  assetsDir: string
 }
 
 export interface DevSessionWatchConfig {

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

@@ -60,6 +60,11 @@ const adminSpecificationSpec = createExtensionSpecification({
     },
   ],
   appModuleFeatures: () => [],
+  appAssetsConfig: (config) => {
+    const dir = config.admin?.static_root
+    if (!dir) return undefined
+    return {assetsKey: 'staticRoot', assetsDir: dir}
+  },
 })
 
 export default adminSpecificationSpec

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

@@ -12,6 +12,7 @@ import {ExtensionInstance} from '../../models/extensions/extension-instance.js'
 import {AbortSignal} from '@shopify/cli-kit/node/abort'
 import {outputDebug} from '@shopify/cli-kit/node/output'
 import {DotEnvFile} from '@shopify/cli-kit/node/dot-env'
+import {getArrayRejectingUndefined} from '@shopify/cli-kit/common/array'
 import {Writable} from 'stream'
 
 export interface ExtensionDevOptions {
@@ -112,6 +113,11 @@ 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?: Record<string, string>
 }
 
 export async function devUIExtensions(options: ExtensionDevOptions): Promise<void> {
@@ -133,7 +139,13 @@ 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})
@@ -144,6 +156,14 @@ export async function devUIExtensions(options: ExtensionDevOptions): Promise<voi
       extensions = app.allExtensions.filter((ext) => ext.isPreviewable)
     }
 
+    // Handle App Assets updates.
+    const appAssetsConfigs = extensionEvents.map((event) =>
+      event.extension.specification.appAssetsConfig?.(event.extension.configuration),
+    )
+    getArrayRejectingUndefined(appAssetsConfigs).forEach((config) => {
+      payloadStore.updateAppAssetTimestamp(config.assetsKey)
+    })
+
     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

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

@@ -9,6 +9,7 @@ import {EventEmitter} from 'events'
 
 export interface ExtensionsPayloadStoreOptions extends ExtensionDevOptions {
   websocketURL: string
+  appAssets?: Record<string, string>
 }
 
 export enum ExtensionsPayloadStoreEvent {
@@ -19,7 +20,7 @@ export async function getExtensionsPayloadStoreRawPayload(
   options: Omit<ExtensionsPayloadStoreOptions, 'appWatcher'>,
   bundlePath: string,
 ): Promise<ExtensionsEndpointPayload> {
-  return {
+  const payload: ExtensionsEndpointPayload = {
     app: {
       title: options.appName,
       apiKey: options.apiKey,
@@ -40,6 +41,18 @@ export async function getExtensionsPayloadStoreRawPayload(
     store: options.storeFqdn,
     extensions: await Promise.all(options.extensions.map((ext) => getUIExtensionPayload(ext, bundlePath, options))),
   }
+
+  if (options.appAssets) {
+    const assets: Record<string, {url: string; lastUpdated: number}> = {}
+    for (const assetKey of Object.keys(options.appAssets)) {
+      assets[assetKey] = {
+        url: new URL(`/extensions/assets/${assetKey}/`, options.url).toString(),
+        lastUpdated: Date.now(),
+      }
+    }
+    payload.app.assets = assets
+  }
+  return payload
 }
 
 export class ExtensionsPayloadStore extends EventEmitter {
@@ -170,6 +183,14 @@ export class ExtensionsPayloadStore extends EventEmitter {
     this.emitUpdate([extension.devUUID])
   }
 
+  updateAppAssetTimestamp(assetKey: string) {
+    const asset = this.rawPayload.app.assets?.[assetKey]
+    if (asset) {
+      asset.lastUpdated = Date.now()
+      this.emitUpdate([])
+    }
+  }
+
   private emitUpdate(extensionIds: string[]) {
     this.emit(ExtensionsPayloadStoreEvent.Update, extensionIds)
   }

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

@@ -2,6 +2,7 @@ import {
   corsMiddleware,
   devConsoleAssetsMiddleware,
   devConsoleIndexMiddleware,
+  getAppAssetsMiddleware,
   getExtensionAssetMiddleware,
   getExtensionPayloadMiddleware,
   getExtensionPointMiddleware,
@@ -19,6 +20,7 @@ interface SetupHTTPServerOptions {
   devOptions: ExtensionsPayloadStoreOptions
   payloadStore: ExtensionsPayloadStore
   getExtensions: () => ExtensionInstance[]
+  getAppAssets?: () => Record<string, string> | undefined
 }
 
 export function setupHTTPServer(options: SetupHTTPServerOptions) {
@@ -28,6 +30,9 @@ export function setupHTTPServer(options: SetupHTTPServerOptions) {
   httpApp.use(getLogMiddleware(options))
   httpApp.use(corsMiddleware)
   httpApp.use(noCacheMiddleware)
+  if (options.getAppAssets) {
+    httpRouter.use('/extensions/assets/:assetKey/**:filePath', getAppAssetsMiddleware(options.getAppAssets))
+  }
   httpRouter.use('/extensions/dev-console', devConsoleIndexMiddleware)
   httpRouter.use('/extensions/dev-console/assets/**:assetPath', devConsoleAssetsMiddleware)
   httpRouter.use('/extensions/:extensionId', getExtensionPayloadMiddleware(options))

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

@@ -134,6 +134,20 @@ export const devConsoleAssetsMiddleware = defineEventHandler(async (event) => {
   })
 })
 
+export function getAppAssetsMiddleware(getAppAssets: () => Record<string, string> | undefined) {
+  return defineEventHandler(async (event) => {
+    const {assetKey = '', filePath = ''} = getRouterParams(event)
+    const appAssets = getAppAssets()
+    const directory = appAssets?.[assetKey]
+    if (!directory) {
+      return sendError(event, {statusCode: 404, statusMessage: `No app assets configured for key: ${assetKey}`})
+    }
+    return fileServerMiddleware(event, {
+      filePath: joinPath(directory, filePath),
+    })
+  })
+}
+
 export function getLogMiddleware({devOptions}: GetExtensionsMiddlewareOptions) {
   return defineEventHandler((event) => {
     outputDebug(`UI extensions server received a ${event.method} request to URL ${event.path}`, devOptions.stdout)

packages/app/src/cli/services/dev/processes/previewable-extension.ts

@@ -24,6 +24,7 @@ interface PreviewableExtensionOptions {
   grantedScopes: string[]
   previewableExtensions: ExtensionInstance[]
   appWatcher: AppEventWatcher
+  appAssetsConfigs: Record<string, string>
 }
 
 export interface PreviewableExtensionProcess extends BaseProcess<PreviewableExtensionOptions> {
@@ -47,6 +48,7 @@ export const launchPreviewableExtensionProcess: DevProcessFunction<PreviewableEx
     previewableExtensions,
     appDirectory,
     appWatcher,
+    appAssetsConfigs,
   },
 ) => {
   await devUIExtensions({
@@ -68,6 +70,7 @@ export const launchPreviewableExtensionProcess: DevProcessFunction<PreviewableEx
     subscriptionProductUrl,
     manifestVersion: MANIFEST_VERSION,
     appWatcher,
+    appAssets: appAssetsConfigs,
   })
 }
 

packages/app/src/cli/services/dev/processes/setup-dev-processes.ts

@@ -149,7 +149,7 @@ export async function setupDevProcesses({
         })
       : undefined,
     await setupPreviewableExtensionsProcess({
-      allExtensions: reloadedApp.allExtensions,
+      allExtensions: reloadedApp.realExtensions,
       storeFqdn,
       storeId,
       apiKey,
@@ -162,6 +162,7 @@ export async function setupDevProcesses({
       appId: remoteApp.id,
       appDirectory: reloadedApp.directory,
       appWatcher,
+      appAssetsConfigs: reloadedApp.appAssetsConfigs,
     }),
     developerPlatformClient.supportsDevSessions
       ? await setupDevSessionProcess({