Extract custom watch paths to specifications

Author: isaacroldan

packages/app/src/cli/models/extensions/extension-instance.ts

@@ -1,6 +1,6 @@
 import {BaseConfigType, MAX_EXTENSION_HANDLE_LENGTH, MAX_UID_LENGTH} from './schemas.js'
 import {FunctionConfigType} from './specifications/function.js'
-import {ExtensionFeature, ExtensionSpecification} from './specification.js'
+import {DevSessionWatchConfig, ExtensionFeature, ExtensionSpecification} from './specification.js'
 import {SingleWebhookSubscriptionType} from './specifications/app_config_webhook_schemas/webhooks_schema.js'
 import {ExtensionBuildOptions, bundleFunctionExtension} from '../../services/build/extension.js'
 import {bundleThemeExtension} from '../../services/extensions/bundle.js'
@@ -277,20 +277,14 @@ export class ExtensionInstance<TConfiguration extends BaseConfigType = BaseConfi
     return [this.entrySourceFilePath]
   }
 
-  // Custom paths to be watched in a dev session
-  // Return undefiend if there aren't custom configured paths (everything is watched)
-  // If there are, include some default paths.
-  get devSessionCustomWatchPaths() {
-    const config = this.configuration as unknown as FunctionConfigType
-    if (!config.build || !config.build.watch) return undefined
-
-    const watchPaths = [config.build.watch].flat().map((path) => joinPath(this.directory, path))
-
-    watchPaths.push(joinPath(this.directory, 'locales', '**.json'))
-    watchPaths.push(joinPath(this.directory, '**', '!(.)*.graphql'))
-    watchPaths.push(joinPath(this.directory, '**.toml'))
-
-    return watchPaths
+  // Custom watch configuration for dev sessions
+  // Return undefined to watch everything (default for 'extension' experience)
+  // Return a config with empty paths to watch nothing (default for 'configuration' experience)
+  get devSessionWatchConfig(): DevSessionWatchConfig | undefined {
+    if (this.specification.devSessionWatchConfig) {
+      return this.specification.devSessionWatchConfig(this)
+    }
+    return this.specification.experience === 'configuration' ? {paths: []} : undefined
   }
 
   async watchConfigurationPaths() {
@@ -436,20 +430,28 @@ export class ExtensionInstance<TConfiguration extends BaseConfigType = BaseConfi
   watchedFiles(): string[] {
     const watchedFiles: string[] = []
 
-    // Add extension directory files based on devSessionCustomWatchPaths or all files
-    const patterns = this.devSessionCustomWatchPaths ?? ['**/*']
+    const defaultIgnore = ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/*.swp', '**/generated/**']
+    const watchConfig = this.devSessionWatchConfig
+
+    if (this.specification.experience === 'configuration' && watchConfig === undefined) {
+      // For configuration experience, if no custom watch config is defined, we only watch the configuration file by default
+      return []
+    }
+
+    const patterns = watchConfig?.paths ?? ['**/*']
+    const ignore = watchConfig?.ignore ?? defaultIgnore
     const files = patterns.flatMap((pattern) =>
       globSync(pattern, {
         cwd: this.directory,
         absolute: true,
         followSymbolicLinks: false,
-        ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/*.swp', '**/generated/**'],
+        ignore,
       }),
     )
     watchedFiles.push(...files.flat())
 
-    // Add imported files from outside the extension directory unless custom watch paths are defined
-    if (!this.devSessionCustomWatchPaths) {
+    // Add imported files from outside the extension directory unless custom watch config is defined
+    if (!watchConfig) {
       const importedFiles = this.scanImports()
       watchedFiles.push(...importedFiles)
     }

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

@@ -136,6 +136,20 @@ export interface ExtensionSpecification<TConfiguration extends BaseConfigType =
    * Copy static assets from the extension directory to the output path
    */
   copyStaticAssets?: (configuration: TConfiguration, directory: string, outputPath: string) => Promise<void>
+
+  /**
+   * Custom watch configuration for dev sessions.
+   * Return a DevSessionWatchConfig with paths to watch and optionally paths to ignore,
+   * or undefined to watch all files in the extension directory.
+   */
+  devSessionWatchConfig?: (extension: ExtensionInstance<TConfiguration>) => DevSessionWatchConfig | undefined
+}
+
+export interface DevSessionWatchConfig {
+  /** Absolute paths or globs to watch */
+  paths: string[]
+  /** Additional glob patterns to ignore (on top of the default ignore list) */
+  ignore?: string[]
 }
 
 /**
@@ -294,6 +308,7 @@ export function createContractBasedModuleSpecification<TConfiguration extends Ba
     | 'clientSteps'
     | 'experience'
     | 'transformRemoteToLocal'
+    | 'devSessionWatchConfig'
   >,
 ) {
   return createExtensionSpecification({

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

@@ -1,8 +1,32 @@
-import {createContractBasedModuleSpecification} from '../specification.js'
+import {createExtensionSpecification} from '../specification.js'
+import {BaseSchemaWithoutHandle} from '../schemas.js'
+import {zod} from '@shopify/cli-kit/node/schema'
+import {joinPath} from '@shopify/cli-kit/node/path'
 
-const adminSpecificationSpec = createContractBasedModuleSpecification({
+const AdminSchema = BaseSchemaWithoutHandle.extend({
+  admin: zod
+    .object({
+      static_root: zod.string().optional(),
+    })
+    .optional(),
+})
+
+const adminSpecificationSpec = createExtensionSpecification({
   identifier: 'admin',
   uidStrategy: 'single',
+  experience: 'configuration',
+  schema: AdminSchema,
+  deployConfig: async (config, _) => {
+    return {admin: config.admin}
+  },
+  devSessionWatchConfig: (extension) => {
+    const staticRoot = extension.configuration.admin?.static_root
+    if (!staticRoot) return {paths: []}
+
+    const roots = [staticRoot].flat()
+    const paths = roots.map((root: string) => joinPath(extension.directory, root, '**/*'))
+    return {paths, ignore: []}
+  },
   transformRemoteToLocal: (remoteContent) => {
     return {
       admin: {

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

@@ -90,6 +90,18 @@ const functionSpec = createExtensionSpecification({
   appModuleFeatures: (_) => ['function'],
   buildConfig: {mode: 'function'},
   getOutputRelativePath: (_extension: ExtensionInstance<FunctionConfigType>) => joinPath('dist', 'index.wasm'),
+  devSessionWatchConfig: (extension: ExtensionInstance<FunctionConfigType>) => {
+    const config = extension.configuration
+    if (!config.build || !config.build.watch) return undefined
+
+    const paths = [config.build.watch].flat().map((path) => joinPath(extension.directory, path))
+
+    paths.push(joinPath(extension.directory, 'locales', '**.json'))
+    paths.push(joinPath(extension.directory, '**', '!(.)*.graphql'))
+    paths.push(joinPath(extension.directory, '**.toml'))
+
+    return {paths}
+  },
   clientSteps: [
     {
       lifecycle: 'deploy',

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

@@ -29,7 +29,9 @@ export async function handleWatcherEvents(
   const appEvent: AppEvent = {app, extensionEvents: [], path: events[0].path, startTime: events[0].startTime}
 
   for (const event of otherEvents) {
-    const affectedExtensions = app.realExtensions.filter((ext) => ext.directory === event.extensionPath)
+    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})
     appEvent.extensionEvents.push(...newEvent.extensionEvents)
   }

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

@@ -76,6 +76,7 @@ interface TestCaseSingleEvent {
   fileSystemEvent: string
   path: string
   expectedEvent?: Omit<WatcherEvent, 'startTime'> & {startTime?: WatcherEvent['startTime']}
+  expectedEventCount?: number
 }
 
 /**
@@ -104,6 +105,7 @@ const singleEventTestCases: TestCaseSingleEvent[] = [
       path: '/extensions/ui_extension_1/index.js',
       extensionPath: '/extensions/ui_extension_1',
     },
+    expectedEventCount: 2,
   },
   {
     name: 'change in toml',
@@ -114,6 +116,7 @@ const singleEventTestCases: TestCaseSingleEvent[] = [
       path: '/extensions/ui_extension_1/shopify.ui.extension.toml',
       extensionPath: '/extensions/ui_extension_1',
     },
+    expectedEventCount: 2,
   },
   {
     name: 'change in app config',
@@ -134,6 +137,7 @@ const singleEventTestCases: TestCaseSingleEvent[] = [
       path: '/extensions/ui_extension_1/new-file.js',
       extensionPath: '/extensions/ui_extension_1',
     },
+    expectedEventCount: 2,
   },
   {
     name: 'delete a file',
@@ -280,7 +284,7 @@ describe('file-watcher events', () => {
 
   test.each(singleEventTestCases)(
     'The event $name returns the expected WatcherEvent',
-    async ({fileSystemEvent, path, expectedEvent}) => {
+    async ({fileSystemEvent, path, expectedEvent, expectedEventCount}) => {
       // Given
       let eventHandler: any
 
@@ -369,7 +373,8 @@ describe('file-watcher events', () => {
               throw new Error('Expected onChange to be called with events, but all calls had empty arrays')
             }
 
-            expect(actualEvents).toHaveLength(1)
+            const eventCount = expectedEventCount ?? 1
+            expect(actualEvents).toHaveLength(eventCount)
             const actualEvent = actualEvents[0]
 
             expect(actualEvent.type).toBe(expectedEvent.type)

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

@@ -19,12 +19,12 @@ const FILE_DELETE_TIMEOUT_IN_MS = 500
 /**
  * Event emitted by the file watcher
  *
- * Includes the type of the event, the path of the file that triggered the event and the extension path that contains the file.
- * path and extensionPath could be the same if the event is at the extension level (create, delete extension)
+ * Includes the type of the event, the path of the file that triggered the event and the extension handle that owns the file.
+ * For folder-level events (create, delete), extensionHandle is undefined since the extension may not exist yet.
  *
  * @typeParam type - The type of the event
  * @typeParam path - The path of the file that triggered the event
- * @typeParam extensionPath - The path of the extension that contains the file
+ * @typeParam extensionHandle - The unique handle of the extension that owns the file
  * @typeParam startTime - The time when the event was triggered
  */
 export interface WatcherEvent {
@@ -37,6 +37,9 @@ export interface WatcherEvent {
     | 'extensions_config_updated'
     | 'app_config_deleted'
   path: string
+  /** The unique handle of the extension that owns this file. Undefined for folder-level events. */
+  extensionHandle?: string
+  /** The directory path of the extension. Used for folder-level events (create/delete) where no extension handle exists yet. */
   extensionPath: string
   startTime: StartTime
 }
@@ -56,7 +59,7 @@ export class FileWatcher {
   private watcher?: FSWatcher
   private readonly debouncedEmit: () => void
   private readonly ignored: {[key: string]: ignore.Ignore | undefined} = {}
-  // Map of file paths to the extensions that watch them
+  // Map of file paths to the extension handles that watch them
   private readonly extensionWatchedFiles = new Map<string, Set<string>>()
 
   constructor(
@@ -115,15 +118,6 @@ export class FileWatcher {
     // Create new watcher
     const {default: chokidar} = await import('chokidar')
     this.watcher = chokidar.watch(watchPaths, {
-      ignored: [
-        '**/node_modules/**',
-        '**/.git/**',
-        '**/*.test.*',
-        '**/dist/**',
-        '**/*.swp',
-        '**/generated/**',
-        '**/.gitignore',
-      ],
       persistent: true,
       ignoreInitial: true,
     })
@@ -155,22 +149,21 @@ 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(),
     }))
 
     const allFiles = new Set<string>()
     for (const {extension, watchedFiles} of extensionResults) {
-      const extensionDir = normalizePath(extension.directory)
       for (const file of watchedFiles) {
         const normalizedPath = normalizePath(file)
         allFiles.add(normalizedPath)
 
-        // Track which extensions watch this file
-        const extensionsSet = this.extensionWatchedFiles.get(normalizedPath) ?? new Set()
-        extensionsSet.add(extensionDir)
-        this.extensionWatchedFiles.set(normalizedPath, extensionsSet)
+        // Track which extension handles watch this file
+        const handlesSet = this.extensionWatchedFiles.get(normalizedPath) ?? new Set()
+        handlesSet.add(extension.handle)
+        this.extensionWatchedFiles.set(normalizedPath, handlesSet)
       }
     }
 
@@ -204,13 +197,13 @@ export class FileWatcher {
     }
 
     // If the event is already in the list, don't push it again
-    // Check path, type, AND extensionPath to properly handle shared files
+    // Check path, type, AND extensionHandle to properly handle shared files
     if (
       this.currentEvents.some(
         (extEvent) =>
           extEvent.path === event.path &&
           extEvent.type === event.type &&
-          extEvent.extensionPath === event.extensionPath,
+          extEvent.extensionHandle === event.extensionHandle,
       )
     )
       return
@@ -229,15 +222,17 @@ export class FileWatcher {
   private shouldIgnoreEvent(event: WatcherEvent) {
     if (event.type === 'extension_folder_deleted' || event.type === 'extension_folder_created') return false
 
-    const extension = this.app.realExtensions.find((ext) => ext.directory === event.extensionPath)
+    const extension = event.extensionHandle
+      ? this.app.realExtensions.find((ext) => ext.handle === event.extensionHandle)
+      : undefined
     const watchPaths = extension?.watchedFiles()
-    const ignoreInstance = this.ignored[event.extensionPath]
+    const ignoreInstance = extension ? this.ignored[extension.directory] : undefined
 
     if (watchPaths) {
       const isAValidWatchedPath = watchPaths.some((pattern) => matchGlob(event.path, pattern))
       return !isAValidWatchedPath
     } else if (ignoreInstance) {
-      const relative = relativePath(event.extensionPath, event.path)
+      const relative = relativePath(extension!.directory, event.path)
       return ignoreInstance.ignores(relative)
     }
 
@@ -255,8 +250,8 @@ export class FileWatcher {
     if (isConfigAppPath) {
       this.handleEventForExtension(event, path, this.app.directory, startTime, false)
     } else {
-      const affectedExtensions = this.extensionWatchedFiles.get(normalizedPath)
-      const isUnknownExtension = affectedExtensions === undefined || affectedExtensions.size === 0
+      const affectedHandles = this.extensionWatchedFiles.get(normalizedPath)
+      const isUnknownExtension = affectedHandles === undefined || affectedHandles.size === 0
 
       if (isUnknownExtension && !isExtensionToml && !isConfigAppPath) {
         // Ignore an event if it's not part of an existing extension
@@ -265,8 +260,10 @@ export class FileWatcher {
         return
       }
 
-      for (const extensionPath of affectedExtensions ?? []) {
-        this.handleEventForExtension(event, path, extensionPath, startTime, false)
+      for (const handle of affectedHandles ?? []) {
+        const extension = this.app.realExtensions.find((ext) => ext.handle === handle)
+        const extensionPath = extension ? normalizePath(extension.directory) : this.app.directory
+        this.handleEventForExtension(event, path, extensionPath, startTime, false, handle)
       }
       if (isUnknownExtension) {
         this.handleEventForExtension(event, path, this.app.directory, startTime, true)
@@ -281,6 +278,7 @@ export class FileWatcher {
     extensionPath: string,
     startTime: StartTime,
     isUnknownExtension: boolean,
+    extensionHandle?: string,
   ) {
     const isExtensionToml = path.endsWith('.extension.toml')
     const isConfigAppPath = path === this.app.configPath
@@ -293,17 +291,17 @@ export class FileWatcher {
           break
         }
         if (isExtensionToml || isConfigAppPath) {
-          this.pushEvent({type: 'extensions_config_updated', path, extensionPath, startTime})
+          this.pushEvent({type: 'extensions_config_updated', path, extensionPath, extensionHandle, startTime})
         } else {
-          this.pushEvent({type: 'file_updated', path, extensionPath, startTime})
+          this.pushEvent({type: 'file_updated', path, extensionPath, extensionHandle, startTime})
         }
         break
       case 'add':
         // If it's a normal non-toml file, just report a file_created event.
         // If a toml file was added, a new extension(s) is being created.
         // We need to wait for the lock file to disappear before triggering the event.
         if (!isExtensionToml) {
-          this.pushEvent({type: 'file_created', path, extensionPath, startTime})
+          this.pushEvent({type: 'file_created', path, extensionPath, extensionHandle, startTime})
           break
         }
         let totalWaitedTime = 0
@@ -339,7 +337,7 @@ export class FileWatcher {
           setTimeout(() => {
             // If the extensionPath is not longer in the list, the extension was deleted while the timeout was running.
             if (!this.extensionPaths.includes(extensionPath)) return
-            this.pushEvent({type: 'file_deleted', path, extensionPath, startTime})
+            this.pushEvent({type: 'file_deleted', path, extensionPath, extensionHandle, startTime})
             // Force an emit because we are inside a timeout callback
             this.debouncedEmit()
           }, FILE_DELETE_TIMEOUT_IN_MS)