Merge pull request #7334 from Shopify/04-16-refactor_remove_buildconfig_from_specifications_in_favor_of_clientsteps

isaacroldan · web-flow · commit 0fe2122d6442 · 2026-04-21T09:09:29.000Z
refactor: remove buildConfig from specifications in favor of clientSteps
diff --git a/packages/app/src/cli/models/extensions/extension-instance.ts b/packages/app/src/cli/models/extensions/extension-instance.ts
@@ -112,6 +112,12 @@ export class ExtensionInstance<TConfiguration extends BaseConfigType = BaseConfi
     return this.specification.identifier === 'editor_extension_collection'
   }
 
+  get hasDeploySteps(): boolean {
+    return (
+      this.specification.clientSteps?.some((group) => group.lifecycle === 'deploy' && group.steps.length > 0) ?? false
+    )
+  }
+
   get features(): ExtensionFeature[] {
     return this.specification.appModuleFeatures(this.configuration)
   }
@@ -340,16 +346,14 @@ export class ExtensionInstance<TConfiguration extends BaseConfigType = BaseConfi
 
     this.outputPath = this.getOutputPathForDirectory(bundleDirectory, extensionUuid)
 
-    const buildMode = this.specification.buildConfig.mode
-
     if (this.isThemeExtension) {
       await bundleThemeExtension(this, options)
-    } else if (buildMode !== 'none') {
+    } else if (this.hasDeploySteps) {
       outputDebug(`Will copy pre-built file from ${defaultOutputPath} to ${this.outputPath}`)
       if (await fileExists(defaultOutputPath)) {
         await copyFile(defaultOutputPath, this.outputPath)
 
-        if (buildMode === 'function') {
+        if (this.isFunctionExtension) {
           await bundleFunctionExtension(this.outputPath, this.outputPath)
         }
       }
diff --git a/packages/app/src/cli/models/extensions/specification.ts b/packages/app/src/cli/models/extensions/specification.ts
@@ -57,10 +57,6 @@ export interface BuildAsset {
   static?: boolean
 }
 
-type BuildConfig =
-  | {mode: 'ui' | 'theme' | 'function' | 'tax_calculation' | 'none' | 'hosted_app_home'}
-  | {mode: 'copy_files'; filePatterns: string[]; ignoredFilePatterns?: string[]}
-
 /**
  * Extension specification with all the needed properties and methods to load an extension.
  */
@@ -75,7 +71,6 @@ export interface ExtensionSpecification<TConfiguration extends BaseConfigType =
   registrationLimit: number
   experience: ExtensionExperience
   clientSteps?: ClientSteps
-  buildConfig: BuildConfig
   dependency?: string
   graphQLType?: string
   getOutputRelativePath?: (extension: ExtensionInstance<TConfiguration>) => string
@@ -220,7 +215,6 @@ export function createExtensionSpecification<TConfiguration extends BaseConfigTy
     uidStrategy: spec.uidStrategy ?? (spec.experience === 'configuration' ? 'single' : 'uuid'),
     getDevSessionUpdateMessages: spec.getDevSessionUpdateMessages,
     clientSteps: spec.clientSteps,
-    buildConfig: spec.buildConfig ?? {mode: 'none'},
   }
   const merged = {...defaults, ...spec}
 
@@ -269,7 +263,6 @@ export function createConfigExtensionSpecification<TConfiguration extends BaseCo
   identifier: string
   schema: ZodSchemaType<TConfiguration>
   clientSteps?: ClientSteps
-  buildConfig?: BuildConfig
   appModuleFeatures?: (config?: TConfiguration) => ExtensionFeature[]
   transformConfig: TransformationConfig | CustomTransformationConfig
   uidStrategy?: UidStrategy
@@ -288,7 +281,6 @@ export function createConfigExtensionSpecification<TConfiguration extends BaseCo
     experience: 'configuration',
     uidStrategy: spec.uidStrategy ?? 'single',
     clientSteps: spec.clientSteps,
-    buildConfig: spec.buildConfig ?? {mode: 'none'},
     getDevSessionUpdateMessages: spec.getDevSessionUpdateMessages,
     patchWithAppDevURLs: spec.patchWithAppDevURLs,
   })
@@ -299,7 +291,6 @@ export function createContractBasedModuleSpecification<TConfiguration extends Ba
     CreateExtensionSpecType<TConfiguration>,
     | 'identifier'
     | 'appModuleFeatures'
-    | 'buildConfig'
     | 'uidStrategy'
     | 'clientSteps'
     | 'experience'
@@ -312,7 +303,6 @@ export function createContractBasedModuleSpecification<TConfiguration extends Ba
     schema: zod.any({}) as unknown as ZodSchemaType<TConfiguration>,
     appModuleFeatures: spec.appModuleFeatures,
     experience: spec.experience,
-    buildConfig: spec.buildConfig ?? {mode: 'none'},
     clientSteps: spec.clientSteps,
     uidStrategy: spec.uidStrategy,
     transformRemoteToLocal: spec.transformRemoteToLocal,
diff --git a/packages/app/src/cli/models/extensions/specifications/admin.ts b/packages/app/src/cli/models/extensions/specifications/admin.ts
@@ -41,10 +41,6 @@ const adminSpecificationSpec = createExtensionSpecification<AdminConfigType>({
       },
     }
   },
-  buildConfig: {
-    mode: 'copy_files',
-    filePatterns: [],
-  },
   clientSteps: [
     {
       lifecycle: 'deploy',
diff --git a/packages/app/src/cli/models/extensions/specifications/channel.ts b/packages/app/src/cli/models/extensions/specifications/channel.ts
@@ -1,5 +1,4 @@
 import {createContractBasedModuleSpecification} from '../specification.js'
-import {joinPath} from '@shopify/cli-kit/node/path'
 
 const SUBDIRECTORY_NAME = 'specifications'
 const FILE_EXTENSIONS = ['json', 'toml', 'yaml', 'yml', 'svg']
@@ -8,10 +7,6 @@ const channelSpecificationSpec = createContractBasedModuleSpecification({
   identifier: 'channel_config',
   uidStrategy: 'single',
   experience: 'extension',
-  buildConfig: {
-    mode: 'copy_files',
-    filePatterns: FILE_EXTENSIONS.map((ext) => joinPath(SUBDIRECTORY_NAME, '**', `*.${ext}`)),
-  },
   clientSteps: [
     {
       lifecycle: 'deploy',
diff --git a/packages/app/src/cli/models/extensions/specifications/checkout_post_purchase.ts b/packages/app/src/cli/models/extensions/specifications/checkout_post_purchase.ts
@@ -16,7 +16,6 @@ const checkoutPostPurchaseSpec = createExtensionSpecification({
   partnersWebIdentifier: 'post_purchase',
   schema: CheckoutPostPurchaseSchema,
   appModuleFeatures: (_) => ['ui_preview', 'cart_url', 'esbuild', 'single_js_entry_path'],
-  buildConfig: {mode: 'ui'},
   getOutputRelativePath: (extension: ExtensionInstance<CheckoutPostPurchaseConfigType>) =>
     `dist/${extension.handle}.js`,
   clientSteps: [
diff --git a/packages/app/src/cli/models/extensions/specifications/checkout_ui_extension.ts b/packages/app/src/cli/models/extensions/specifications/checkout_ui_extension.ts
@@ -23,7 +23,6 @@ const checkoutSpec = createExtensionSpecification({
   dependency,
   schema: CheckoutSchema,
   appModuleFeatures: (_) => ['ui_preview', 'cart_url', 'esbuild', 'single_js_entry_path', 'generates_source_maps'],
-  buildConfig: {mode: 'ui'},
   getOutputRelativePath: (extension: ExtensionInstance<CheckoutConfigType>) => `dist/${extension.handle}.js`,
   clientSteps: [
     {
diff --git a/packages/app/src/cli/models/extensions/specifications/flow_template.ts b/packages/app/src/cli/models/extensions/specifications/flow_template.ts
@@ -49,7 +49,6 @@ const flowTemplateSpec = createExtensionSpecification({
   identifier: 'flow_template',
   schema: FlowTemplateExtensionSchema,
   appModuleFeatures: (_) => ['ui_preview'],
-  buildConfig: {mode: 'copy_files', filePatterns: ['**/*.flow', '**/*.json', '**/*.toml']},
   clientSteps: [
     {
       lifecycle: 'deploy',
diff --git a/packages/app/src/cli/models/extensions/specifications/function.ts b/packages/app/src/cli/models/extensions/specifications/function.ts
@@ -88,7 +88,6 @@ const functionSpec = createExtensionSpecification({
   ],
   schema: FunctionExtensionSchema,
   appModuleFeatures: (_) => ['function'],
-  buildConfig: {mode: 'function'},
   getOutputRelativePath: (_extension: ExtensionInstance<FunctionConfigType>) => joinPath('dist', 'index.wasm'),
   devSessionWatchConfig: (extension: ExtensionInstance<FunctionConfigType>) => {
     const config = extension.configuration
diff --git a/packages/app/src/cli/models/extensions/specifications/pos_ui_extension.ts b/packages/app/src/cli/models/extensions/specifications/pos_ui_extension.ts
@@ -15,7 +15,6 @@ const posUISpec = createExtensionSpecification({
   dependency,
   schema: PosUISchema,
   appModuleFeatures: (_) => ['ui_preview', 'esbuild', 'single_js_entry_path'],
-  buildConfig: {mode: 'ui'},
   getOutputRelativePath: (extension: ExtensionInstance<PosUIConfigType>) => `dist/${extension.handle}.js`,
   clientSteps: [
     {
diff --git a/packages/app/src/cli/models/extensions/specifications/product_subscription.ts b/packages/app/src/cli/models/extensions/specifications/product_subscription.ts
@@ -16,7 +16,6 @@ const productSubscriptionSpec = createExtensionSpecification({
   graphQLType: 'subscription_management',
   schema: BaseSchema,
   appModuleFeatures: (_) => ['ui_preview', 'esbuild', 'single_js_entry_path'],
-  buildConfig: {mode: 'ui'},
   getOutputRelativePath: (extension: ExtensionInstance<ProductSubscriptionConfigType>) => `dist/${extension.handle}.js`,
   clientSteps: [
     {
diff --git a/packages/app/src/cli/models/extensions/specifications/tax_calculation.ts b/packages/app/src/cli/models/extensions/specifications/tax_calculation.ts
@@ -31,7 +31,6 @@ const spec = createExtensionSpecification({
   identifier: 'tax_calculation',
   schema: TaxCalculationsSchema,
   appModuleFeatures: (_) => [],
-  buildConfig: {mode: 'tax_calculation'},
   getOutputRelativePath: (extension: ExtensionInstance<TaxCalculationsConfigType>) =>
     joinPath('dist', `${extension.handle}.js`),
   clientSteps: [
diff --git a/packages/app/src/cli/models/extensions/specifications/theme.ts b/packages/app/src/cli/models/extensions/specifications/theme.ts
@@ -12,7 +12,6 @@ const themeSpec = createExtensionSpecification({
   schema: BaseSchema,
   partnersWebIdentifier: 'theme_app_extension',
   graphQLType: 'theme_app_extension',
-  buildConfig: {mode: 'theme'},
   clientSteps: [
     {
       lifecycle: 'deploy',
diff --git a/packages/app/src/cli/models/extensions/specifications/ui_extension.ts b/packages/app/src/cli/models/extensions/specifications/ui_extension.ts
@@ -83,7 +83,6 @@ const uiExtensionSpec = createExtensionSpecification({
   identifier: 'ui_extension',
   dependency,
   schema: UIExtensionSchema,
-  buildConfig: {mode: 'ui'},
   getOutputRelativePath: (extension: ExtensionInstance<UIExtensionConfigType>) => `dist/${extension.handle}.js`,
   clientSteps: [
     {
diff --git a/packages/app/src/cli/models/extensions/specifications/web_pixel_extension.ts b/packages/app/src/cli/models/extensions/specifications/web_pixel_extension.ts
@@ -33,7 +33,6 @@ const webPixelSpec = createExtensionSpecification({
   partnersWebIdentifier: 'web_pixel',
   schema: WebPixelSchema,
   appModuleFeatures: (_) => ['esbuild', 'single_js_entry_path'],
-  buildConfig: {mode: 'ui'},
   getOutputRelativePath: (extension: ExtensionInstance<WebPixelConfigType>) => `dist/${extension.handle}.js`,
   clientSteps: [
     {
diff --git a/packages/app/src/cli/services/deploy.test.ts b/packages/app/src/cli/services/deploy.test.ts
@@ -79,6 +79,12 @@ beforeEach(() => {
 
   // Mock filterOutImportedExtensions to return the extensions by default
   vi.mocked(filterOutImportedExtensions).mockImplementation((_app, extensions) => extensions)
+
+  // Mirror real bundleAndBuildExtensions behavior: return the bundlePath when
+  // at least one extension has deploy steps, otherwise undefined.
+  vi.mocked(bundleAndBuildExtensions).mockImplementation(async (opts) =>
+    opts.app.allExtensions.some((ext) => ext.hasDeploySteps) ? opts.bundlePath : undefined,
+  )
 })
 
 describe('deploy', () => {
diff --git a/packages/app/src/cli/services/deploy.ts b/packages/app/src/cli/services/deploy.ts
@@ -213,20 +213,19 @@ export async function deploy(options: DeployOptions) {
   let uploadExtensionsBundleResult!: UploadExtensionsBundleOutput
 
   try {
-    const bundle = app.allExtensions.some((ext) => ext.specification.buildConfig.mode !== 'none')
-    let bundlePath: string | undefined
-
-    if (bundle) {
-      bundlePath = joinPath(options.app.directory, '.shopify', `deploy-bundle.${developerPlatformClient.bundleFormat}`)
-      await mkdir(dirname(bundlePath))
-    }
+    const candidateBundlePath = joinPath(
+      options.app.directory,
+      '.shopify',
+      `deploy-bundle.${developerPlatformClient.bundleFormat}`,
+    )
+    await mkdir(dirname(candidateBundlePath))
 
     const appManifest = await app.manifest(identifiers)
 
-    await bundleAndBuildExtensions({
+    const bundlePath = await bundleAndBuildExtensions({
       app,
       appManifest,
-      bundlePath,
+      bundlePath: candidateBundlePath,
       identifiers,
       skipBuild: options.skipBuild,
       isDevDashboardApp: developerPlatformClient.supportsAtomicDeployments,
diff --git a/packages/app/src/cli/services/deploy/bundle.test.ts b/packages/app/src/cli/services/deploy/bundle.test.ts
@@ -1,5 +1,11 @@
 import {bundleAndBuildExtensions} from './bundle.js'
-import {testApp, testFunctionExtension, testThemeExtensions, testUIExtension} from '../../models/app/app.test-data.js'
+import {
+  testApp,
+  testAppConfigExtensions,
+  testFunctionExtension,
+  testThemeExtensions,
+  testUIExtension,
+} from '../../models/app/app.test-data.js'
 import {AppInterface, AppManifest, WebType} from '../../models/app/app.js'
 import * as bundle from '../bundle.js'
 import * as functionBuild from '../function/build.js'
@@ -477,4 +483,38 @@ describe('bundleAndBuildExtensions', () => {
       await expect(file.fileExists(bundlePath)).resolves.toBeTruthy()
     })
   })
+
+  test('returns undefined and skips compression when no extension has deploy steps', async () => {
+    await file.inTemporaryDirectory(async (tmpDir: string) => {
+      // Given
+      const bundlePath = joinPath(tmpDir, '.shopify', 'deploy-bundle.zip')
+      const compressSpy = vi.spyOn(bundle, 'compressBundle').mockResolvedValue()
+
+      const configExtension = await testAppConfigExtensions()
+      const app = testApp({allExtensions: [configExtension], directory: tmpDir})
+
+      const identifiers = {
+        app: 'app-id',
+        extensions: {},
+        extensionIds: {},
+        extensionsNonUuidManaged: {[configExtension.localIdentifier]: configExtension.localIdentifier},
+      }
+      appManifest = await app.manifest(identifiers)
+
+      // When
+      const result = await bundleAndBuildExtensions({
+        app,
+        appManifest,
+        identifiers,
+        bundlePath,
+        skipBuild: false,
+        isDevDashboardApp: false,
+      })
+
+      // Then
+      expect(result).toBeUndefined()
+      expect(compressSpy).not.toHaveBeenCalled()
+      await expect(file.fileExists(bundlePath)).resolves.toBe(false)
+    })
+  })
 })
diff --git a/packages/app/src/cli/services/deploy/bundle.ts b/packages/app/src/cli/services/deploy/bundle.ts
@@ -12,13 +12,19 @@ import {Writable} from 'stream'
 interface BundleOptions {
   app: AppInterface
   appManifest: AppManifest
-  bundlePath?: string
+  bundlePath: string
   identifiers?: Identifiers
   skipBuild: boolean
   isDevDashboardApp: boolean
 }
 
-export async function bundleAndBuildExtensions(options: BundleOptions) {
+/**
+ * Builds all extensions into a bundle directory and compresses it when at
+ * least one extension declares deploy steps. Returns the bundlePath in that
+ * case, or undefined when no extension has deploy steps and there's nothing
+ * to upload beyond the manifest.
+ */
+export async function bundleAndBuildExtensions(options: BundleOptions): Promise<string | undefined> {
   const bundleDirectory = joinPath(options.app.directory, '.shopify', 'deploy-bundle')
   await rmdir(bundleDirectory, {force: true})
   await mkdir(bundleDirectory)
@@ -73,7 +79,12 @@ export async function bundleAndBuildExtensions(options: BundleOptions) {
     showTimestamps: false,
   })
 
-  if (options.bundlePath) {
+  const hasExtensionOutput = options.app.allExtensions.some((ext) => ext.hasDeploySteps)
+
+  if (hasExtensionOutput) {
     await compressBundle(bundleDirectory, options.bundlePath)
+    return options.bundlePath
   }
+
+  return undefined
 }

Original file line number	Diff line number	Diff line change
`@@ -41,10 +41,6 @@ const adminSpecificationSpec = createExtensionSpecification<AdminConfigType>({`
`41`	`41`	`},`
`42`	`42`	`}`
`43`	`43`	`},`
`44`		`- buildConfig: {`
`45`		`- mode: 'copy_files',`
`46`		`- filePatterns: [],`
`47`		`- },`
`48`	`44`	`clientSteps: [`
`49`	`45`	`{`
`50`	`46`	`lifecycle: 'deploy',`
Original file line number	Diff line number	Diff line change
`@@ -23,7 +23,6 @@ const checkoutSpec = createExtensionSpecification({`
`23`	`23`	`dependency,`
`24`	`24`	`schema: CheckoutSchema,`
`25`	`25`	`appModuleFeatures: (_) => ['ui_preview', 'cart_url', 'esbuild', 'single_js_entry_path', 'generates_source_maps'],`
`26`		`- buildConfig: {mode: 'ui'},`
`27`	`26`	getOutputRelativePath: (extension: ExtensionInstance<CheckoutConfigType>) => `dist/${extension.handle}.js`,
`28`	`27`	`clientSteps: [`
`29`	`28`	`{`
Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,6 @@ const flowTemplateSpec = createExtensionSpecification({`
`49`	`49`	`identifier: 'flow_template',`
`50`	`50`	`schema: FlowTemplateExtensionSchema,`
`51`	`51`	`appModuleFeatures: (_) => ['ui_preview'],`
`52`		`- buildConfig: {mode: 'copy_files', filePatterns: ['*/.flow', '*/.json', '*/.toml']},`
`53`	`52`	`clientSteps: [`
`54`	`53`	`{`
`55`	`54`	`lifecycle: 'deploy',`
Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,6 @@ const posUISpec = createExtensionSpecification({`
`15`	`15`	`dependency,`
`16`	`16`	`schema: PosUISchema,`
`17`	`17`	`appModuleFeatures: (_) => ['ui_preview', 'esbuild', 'single_js_entry_path'],`
`18`		`- buildConfig: {mode: 'ui'},`
`19`	`18`	getOutputRelativePath: (extension: ExtensionInstance<PosUIConfigType>) => `dist/${extension.handle}.js`,
`20`	`19`	`clientSteps: [`
`21`	`20`	`{`
Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,6 @@ const productSubscriptionSpec = createExtensionSpecification({`
`16`	`16`	`graphQLType: 'subscription_management',`
`17`	`17`	`schema: BaseSchema,`
`18`	`18`	`appModuleFeatures: (_) => ['ui_preview', 'esbuild', 'single_js_entry_path'],`
`19`		`- buildConfig: {mode: 'ui'},`
`20`	`19`	getOutputRelativePath: (extension: ExtensionInstance<ProductSubscriptionConfigType>) => `dist/${extension.handle}.js`,
`21`	`20`	`clientSteps: [`
`22`	`21`	`{`