Create abstract client steps infrastracture to externalize the ap modules client configurations by alfonso-noriega · Pull Request #6965 · Shopify/cli

alfonso-noriega · 2026-03-10T08:34:04Z

WHY are these changes introduced?

This introduces a new client-side build pipeline system to replace the existing buildConfig approach for extensions. The current system is limited and doesn't provide enough flexibility for complex build scenarios.

WHAT is this pull request doing?

Adds a new ClientSteps interface that defines build steps as configuration objects with execution handled separately
Introduces BuildContext to pass data through the step pipeline and store results
Implements step executors for build_function, build_theme, bundle_theme, and bundle_ui operations
Adds an include_assets step type with support for pattern-based and config-key-based file inclusions
Updates ExtensionSpecification to include optional clientSteps field alongside existing buildConfig
Modifies buildForBundle method to handle app config extensions differently by using the extension UID as the output path
Adds null coalescing operators to prevent undefined errors when filePatterns and ignoredFilePatterns are not defined
Includes comprehensive test coverage for the new client steps system

How to test your changes?

Create an extension that uses the new clientSteps configuration
Run the build process and verify that steps execute in sequence
Test the include_assets step with both pattern and configKey inclusion types
Verify that error handling works correctly with continueOnError flag
Ensure existing extensions using buildConfig continue to work unchanged

Measuring impact

How do we know this change was effective? Please choose one:

n/a - this doesn't need measurement, e.g. a linting rule or a bug-fix

Checklist

I've considered possible cross-platform impacts (Mac, Linux, Windows)
I've considered possible documentation changes

alfonso-noriega · 2026-03-10T08:34:22Z

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

This stack of pull requests is managed by Graphite. Learn more about stacking.

github-actions · 2026-03-10T08:35:06Z

We detected some changes at packages/*/src and there are no updates in the .changeset.
If the changes are user-facing, run pnpm changeset add to track your changes and include them in the next release CHANGELOG.

Caution

DO NOT create changesets for features which you do not wish to be included in the public changelog of the next CLI release.

isaacroldan · 2026-03-10T08:48:21Z

packages/app/src/cli/services/generate/fetch-extension-specifications.ts

      FlattenedRemoteSpecification

+    // Not all the specs are moved to remote definition yet
+    merged.clientSteps ??= localSpec.clientSteps ?? []


Is this necessary? :thinking_face:
when merging in the previous step, is remoteSpec setting this to undefined? or is it preserving the localSpec value?

isaacroldan · 2026-03-10T09:04:49Z

packages/app/src/cli/services/build/client-steps.ts

+interface StepResult {
+  readonly id: string
+  readonly success: boolean
+  readonly duration: number
+  readonly output?: unknown
+  readonly error?: Error
+}


We should be more strict with this type:

type StepResult = StepError | StepSuccess interface StepResultMetadata { readonly id: string readonly duration: number } type StepError = StepResultMetadata & { readonly success: false readonly error: Error } type StepSuccess = StepResultMetadata & { readonly success: true readonly output: unknown }

Which can also me simplified into:

type StepResult = { readonly id: string readonly duration: number } & ({ readonly success: false readonly error: Error } | { readonly success: true readonly output: unknown })

isaacroldan · 2026-03-10T09:07:04Z

packages/app/src/cli/services/build/client-steps.ts

+ * The full client steps configuration for an extension.
+ * Replaces the old buildConfig contract.
+ */
+export type ClientSteps = ReadonlyArray<ClientLifecycleGroup>


is a bit weird that ClientSteps is not array of ClientStep, but an array of ClientLifecycleGroupthat then contains an array of ClientStep :thinking_face:

Not sure if we should find a different name for either ClientSteps or ClientStep

isaacroldan · 2026-03-10T09:08:12Z

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

+type BuildMode = 'copy_files' | 'theme' | 'function' | 'ui' | 'tax_calculation' | 'hosted_app_home' | 'none'
+
+interface BuildConfig {
+  mode: BuildMode
+  filePatterns?: string[]
+  ignoredFilePatterns?: string[]
+}


Why this change? is it necessary? it is technically wrong to express the type like this (with optional patterns for every mode)

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

binks-code-reviewer · 2026-03-10T11:33:22Z

packages/app/src/cli/services/build/steps/index.ts

+    case 'validate':
+    case 'transform':
+    case 'custom':
+      throw new Error(`Build step type "${step.type}" is not yet implemented.`)


Step router makes all step types unusable (always throws)

executeStepByType explicitly throws for every declared step type (including include_assets, bundle_ui, bundle_theme, etc.), so the new ClientSteps pipeline cannot execute any step successfully.

Evidence:

case 'include_assets': ... throw new Error(`Build step type "${step.type}" is not yet implemented.`)

Impact:

Any runtime path using clientSteps will fail during build/deploy.

CI/build pipelines will error; deploys could be blocked broadly once enabled.

binks-code-reviewer · 2026-03-10T11:33:23Z

⚠️ Findings outside the diff

These findings are in files not modified by this PR and cannot be posted as inline comments.

packages/app/src/cli/services/build/client-steps.integration.test.ts:168 — Integration tests assert copying behavior but no implementation exists

The integration test calls executeStep with type: 'include_assets' and asserts files were copied into outputDir, but the router currently throws “not yet implemented” for include_assets, so this test should fail consistently.

Evidence:

await executeStep({ ..., type: 'include_assets', ... }, context)
...
expect(await fileExists(joinPath(outputDir, 'logo.png'))).toBe(true)

Impact:

PR should fail CI (or indicates these tests aren’t running).
Confirms the core feature is incomplete.

binks-code-reviewer · 2026-03-10T11:33:23Z

packages/app/src/cli/services/build/client-steps.ts

+      success: true,
+      duration: Date.now() - startTime,
+      output,
+    }


BuildContext.stepResults is never written to, despite being part of the contract

BuildContext includes stepResults: Map<string, StepResult> and ClientStep.id is described as the “key in the stepResults map”, but executeStep never stores the produced result into context.stepResults. This breaks intended pipeline behavior (later steps can’t inspect prior outputs/errors) and can cause subtle bugs once steps depend on previous results.

binks-code-reviewer · 2026-03-10T11:33:24Z

🤖 Code Review · #projects-dev-ai for questions
React with 👍/👎 or reply — all feedback helps improve the agent.

✅ Complete - No issues

📋 History

❌ Failed → ❌ Failed → ❌ Failed → ✅ 2 findings → ✅ No issues → ❌ Failed → ❌ Failed → ✅ No issues → ✅ No issues

binks-code-reviewer · 2026-03-10T12:04:07Z

⚠️ Findings outside the diff

These findings are in files not modified by this PR and cannot be posted as inline comments.

packages/app/src/cli/models/extensions/extension-instance.ts:369 — New build mode 'hosted_app_home' is added to the type but not handled in build switch

BuildConfig.mode includes 'hosted_app_home', but ExtensionInstance.build() does not handle it. The extension may not be built, producing missing artifacts.

Impact: Specs setting mode=hosted_app_home can lead to deploy failures or missing runtime resources.

github-actions · 2026-03-10T14:59:29Z

Coverage report

St.^❔	Category	Percentage	Covered / Total
🟡	Statements	78.83%	14491/18383
🟡	Branches	73%	7201/9864
🟡	Functions	79.07%	3703/4683
🟡	Lines	79.17%	13690/17292

Test suite run success

3795 tests passing in 1452 suites.

Report generated by 🧪jest coverage report action from b42a87b

…ules client configurations

ryancbahan · 2026-03-10T15:46:24Z

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

 export function createConfigExtensionSpecification<TConfiguration extends BaseConfigType = BaseConfigType>(spec: {
  identifier: string
  schema: ZodSchemaType<TConfiguration>
+  clientSteps?: ClientSteps


is clientSteps meant to eventually replace buildconfig or are we intending to support both?

ryancbahan · 2026-03-10T15:49:19Z

packages/app/src/cli/services/build/client-steps.ts

+  readonly extension: ExtensionInstance
+  readonly options: ExtensionBuildOptions
+  readonly stepResults: Map<string, StepResult>
+  [key: string]: unknown


ideally outputs are not unknown if there is a finite amount of valid steps

ryancbahan · 2026-03-10T15:50:49Z

packages/app/src/cli/services/build/client-steps.ts

+ * Context passed through the step pipeline.
+ * Each step can read from and write to the context.
+ */
+export interface BuildContext {


i'm unclear on why an additional stateful context is necessary. can we not iterate through the steps just using the data already available and the step i/o?

This was referenced Mar 10, 2026

Refactor extension build process to use modular build steps #6867

Open

Read client steps from remote config #6941

Open

Replace hosted_app_home build mode with copy_files mode #6868

Closed

Add a build manifest build step #6869

Open

alfonso-noriega mentioned this pull request Mar 10, 2026

Add client steps implementation to support existing functionalities #6966

Open

3 tasks

alfonso-noriega marked this pull request as ready for review March 10, 2026 08:34

alfonso-noriega requested a review from a team as a code owner March 10, 2026 08:34

isaacroldan reviewed Mar 10, 2026

View reviewed changes

alfonso-noriega force-pushed the 03-10-create_abstract_client_steps_infrastracture_to_externalize_the_ap_modules_client_configurations branch from 16768f3 to 59f0139 Compare March 10, 2026 09:59

alfonso-noriega mentioned this pull request Mar 10, 2026

Clean up module outputFile calculation and move it to the specifications #6967

Open

3 tasks

alfonso-noriega changed the base branch from main to graphite-base/6965 March 10, 2026 11:07

alfonso-noriega force-pushed the 03-10-create_abstract_client_steps_infrastracture_to_externalize_the_ap_modules_client_configurations branch from 59f0139 to f9f9e63 Compare March 10, 2026 11:07

alfonso-noriega changed the base branch from graphite-base/6965 to 03-10-clean_up_module_outputfile_calculation_and_move_it_to_the_specifications March 10, 2026 11:07

alfonso-noriega force-pushed the 03-10-clean_up_module_outputfile_calculation_and_move_it_to_the_specifications branch from 7b68eb7 to c3ee349 Compare March 10, 2026 11:24

alfonso-noriega force-pushed the 03-10-create_abstract_client_steps_infrastracture_to_externalize_the_ap_modules_client_configurations branch from f9f9e63 to 59dcaa7 Compare March 10, 2026 11:24

binks-code-reviewer bot reviewed Mar 10, 2026

View reviewed changes

alfonso-noriega force-pushed the 03-10-create_abstract_client_steps_infrastracture_to_externalize_the_ap_modules_client_configurations branch from 59dcaa7 to fb4c01d Compare March 10, 2026 11:35

alfonso-noriega force-pushed the 03-10-create_abstract_client_steps_infrastracture_to_externalize_the_ap_modules_client_configurations branch from fb4c01d to 68f4751 Compare March 10, 2026 12:15

alfonso-noriega force-pushed the 03-10-clean_up_module_outputfile_calculation_and_move_it_to_the_specifications branch 2 times, most recently from 24fb214 to ecf7d0f Compare March 10, 2026 12:41

alfonso-noriega force-pushed the 03-10-create_abstract_client_steps_infrastracture_to_externalize_the_ap_modules_client_configurations branch 4 times, most recently from 9257821 to 596be94 Compare March 10, 2026 14:45

alfonso-noriega force-pushed the 03-10-create_abstract_client_steps_infrastracture_to_externalize_the_ap_modules_client_configurations branch from 596be94 to e088f88 Compare March 10, 2026 14:52

Create abstract client steps infrastracture to externalize the ap mod…

b42a87b

…ules client configurations

alfonso-noriega force-pushed the 03-10-create_abstract_client_steps_infrastracture_to_externalize_the_ap_modules_client_configurations branch from e088f88 to b42a87b Compare March 10, 2026 15:18

ryancbahan reviewed Mar 10, 2026

View reviewed changes

Conversation

alfonso-noriega commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

WHY are these changes introduced?

WHAT is this pull request doing?

How to test your changes?

Measuring impact

Checklist

Uh oh!

alfonso-noriega commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 10, 2026

Uh oh!

isaacroldan Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

isaacroldan Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

isaacroldan Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

isaacroldan Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

binks-code-reviewer bot Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

binks-code-reviewer bot commented Mar 10, 2026

Uh oh!

binks-code-reviewer bot Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

binks-code-reviewer bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

binks-code-reviewer bot commented Mar 10, 2026

Uh oh!

github-actions bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report

Test suite run success

Uh oh!

ryancbahan Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

ryancbahan Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

ryancbahan Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alfonso-noriega commented Mar 10, 2026 •

edited

Loading

alfonso-noriega commented Mar 10, 2026 •

edited

Loading

binks-code-reviewer bot commented Mar 10, 2026 •

edited

Loading

github-actions bot commented Mar 10, 2026 •

edited

Loading