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/extension-instance.ts

@@ -285,7 +285,7 @@ export class ExtensionInstance<TConfiguration extends BaseConfigType = BaseConfi
       return this.specification.devSessionWatchConfig(this)
     }
 
-    return this.specification.experience === 'configuration' ? {paths: []} : undefined
+    return this.isAppConfigExtension ? {paths: []} : undefined
   }
 
   async watchConfigurationPaths() {

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

@@ -62,6 +62,11 @@ const adminSpecificationSpec = createExtensionSpecification<AdminConfigType>({
     },
   ],
   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/build/steps/include-assets-step.test.ts

@@ -1044,7 +1044,7 @@ describe('executeIncludeAssetsStep', () => {
       )
     })
 
-    test('throws when manifest.json already exists in the output directory', async () => {
+    test('overwrites manifest.json when it already exists in the output directory', async () => {
       // Given — a prior inclusion already copied a manifest.json to the output dir
       const contextWithConfig = {
         ...mockContext,
@@ -1056,8 +1056,7 @@ describe('executeIncludeAssetsStep', () => {
         } as unknown as ExtensionInstance,
       }
 
-      // Source files exist; output manifest.json already exists (simulating conflict);
-      // candidate output paths for tools.json are free so copyConfigKeyEntry succeeds.
+      // Source files exist; output manifest.json already exists
       vi.mocked(fs.fileExists).mockImplementation(async (path) => {
         const pathStr = String(path)
         return pathStr === '/test/output/manifest.json' || pathStr.startsWith('/test/extension/')
@@ -1081,9 +1080,11 @@ describe('executeIncludeAssetsStep', () => {
         },
       }
 
-      // When / Then — throws rather than silently overwriting
-      await expect(executeIncludeAssetsStep(step, contextWithConfig)).rejects.toThrow(
-        `Can't write manifest.json: a file already exists at '/test/output/manifest.json'`,
+      // When / Then — overwrites existing manifest.json
+      await expect(executeIncludeAssetsStep(step, contextWithConfig)).resolves.not.toThrow()
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        '/test/output/manifest.json',
+        expect.any(String),
       )
     })
 

packages/app/src/cli/services/build/steps/include-assets/generate-manifest.ts

@@ -1,6 +1,6 @@
 import {getNestedValue, tokenizePath} from './copy-config-key-entry.js'
 import {joinPath} from '@shopify/cli-kit/node/path'
-import {fileExists, mkdir, writeFile} from '@shopify/cli-kit/node/fs'
+import {mkdir, writeFile} from '@shopify/cli-kit/node/fs'
 import {outputDebug} from '@shopify/cli-kit/node/output'
 import type {BuildContext} from '../../client-steps.js'
 
@@ -20,7 +20,7 @@ interface ConfigKeyManifestEntry {
  * 3. Build root-level entries.
  * 4. Build grouped entries (anchor/groupBy logic) with path strings resolved
  *    via `resolveManifestPaths` using the copy-tracked `pathMap`.
- * 5. Write `outputDir/manifest.json`; throw if the file already exists.
+ * 5. Write `outputDir/manifest.json`, overwriting any existing file.
  *
  * @param pathMap - Map from raw config path values to their output-relative
  *   paths, as recorded during the copy phase by `copyConfigKeyEntry`.
@@ -113,12 +113,6 @@ export async function generateManifestFile(
   }
 
   const manifestPath = joinPath(outputDir, 'manifest.json')
-  if (await fileExists(manifestPath)) {
-    throw new Error(
-      `Can't write manifest.json: a file already exists at '${manifestPath}'. ` +
-        `Remove or rename the conflicting inclusion to avoid overwriting the generated manifest.`,
-    )
-  }
   await mkdir(outputDir)
   await writeFile(manifestPath, JSON.stringify(manifest, null, 2))
   outputDebug(`Generated manifest.json in ${outputDir}\n`, options.stdout)

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

@@ -150,7 +150,7 @@ export class FileWatcher {
   private getAllWatchedFiles(): string[] {
     this.extensionWatchedFiles.clear()
 
-    const extensionResults = this.app.nonConfigExtensions.map((extension) => ({
+    const extensionResults = this.app.realExtensions.map((extension) => ({
       extension,
       watchedFiles: extension.watchedFiles(),
     }))

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)
   }