Support single-subscription events modules when reading remote configuration by rezaansyed · Pull Request #8425 · Shopify/cli

rezaansyed · 2026-08-28T18:57:19Z

Context

As part of supporting shop-scoped event subscriptions, we now support a dual contract for the events module where it may either be a single subscription object (new) or a list of subscriptions. We want to move away from having two contracts and move towards a single contract as it brings forth a better DX with regards to subscription management and maintains consistency across shop-scoped and app-versioned events modules.

The CLI's events transforms are currently hard-typed to the list shape: transformToEventsConfig calls .map on subscription and crashes on an object, and config link would need N single-subscription modules to merge back into one [[events.subscription]] list in the local TOML.

WHAT is this pull request doing?

transformToEventsConfig (remote → local): accepts a single-subscription object or the legacy array. N single-subscription modules are transformed into a list in the TOML so as to maintain the existing TOML structure.
transformToEventsConfig also strips a subscription's api_version when it equals the module-level events.api_version. An api_version that differs from the default is a genuine per-subscription override and is kept.
transformFromEventsConfig (local → remote): resolves relative subscription URIs for both shapes, preserving the input shape.

The local TOML format is unchanged: [[events.subscription]] stays a list, and api_version appears on a subscription only when it overrides the section default. This is read-side tolerance only.

How to test your changes?

With an app in your local environment, test shopify app config link. It should continue working as normal.

Post-release steps

None.

Measuring impact

n/a: covered by existing events module metrics in Core

Checklist

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

…uration Assisted-By: devx/aa56a38c-289a-416e-8a9a-0de281e4e3e7

…vents configuration Assisted-By: devx/aa56a38c-289a-416e-8a9a-0de281e4e3e7

…nking config When Core returns events modules where subscriptions have no handle, fall back to the parent module's registration title (except for the default 'events' handle) so each single-subscription module retains its identity when merged into the local configuration. Pass the identity through the generic reverse-transform options as module.handle, matching the shared module context other specifications consume.

isaacroldan · 2026-09-29T15:59:33Z


+  const subscription = eventsConfig.events.subscription
+  const resolved = wrapSubscriptions(subscription).map((sub) =>
+    typeof sub.uri === 'string' ? {...sub, uri: prependApplicationUrl(sub.uri, appUrl)} : sub,


I know this prepend already existed but... is it needed?

If this is true:

On deploy, the backend accepts relative URLs right?

On dev, we don't want to use real URLs (we want to use the tunnel URL)

And assuming this:

We don't update the toml with the tunnel URL anymore during dev, so it will always have a "real" one.

So... isn't it better to keep the relative URLs in the toml and prepend them ONLY during dev?

We could but this would change how link currently works as the module stores the full URI today and would return that as part of link. This isn't really a changing existing behaviour so maybe we can address this as a separate PR to unblock this one?

isaacroldan · 2026-09-30T09:07:13Z

+  if (Array.isArray(subscription)) {
+    cleanedSubscriptions = subscription.map(clean)
+  } else if (subscription) {
+    const handle = subscription.handle ?? moduleHandle


is there any risk on using the moduleHandle as default here? can it lead to duplicate handles in any way?

If yes -> maybe we need to use something random here
If not -> Can we then just use a hardcoded default to avoid passing the module handle to the transform function? It can be something like: events-handle or {subscription.identifier}

In the function signature we are even saying that moduleHandle is optional, so there is even a possibility where handle is undefined here, with a hardcoded/computed value here we prevent that and also simplify the changes a lot in this PR

Core keeps a single-subscription handle on the module and rejects it inside the subscription. The handle is also the module uid and the seed of the subscription identifier, so a handle derived from the topic and actions changes the module identity after config link, and can collide when two subscriptions share a topic and actions. Pass the module handle to the reverse transform and keep the derived handle only as a fallback. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

The remote side of the breakdown restores each single-subscription handle from its module. Pass the local module handle too, so matching modules don't show the events section as updated on every deploy. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

…dules The platform derives a single-subscription module's runtime handle, uid and identifier from the module handle and rejects a nested handle on write, so a nested handle can only survive on older versions and must not win over the module handle when linking.

…rsion

rezaansyed mentioned this pull request Aug 28, 2026

One events module per subscription behind an organization flag or environment opt-in on app deploys #8426

Closed

3 tasks done

github-actions Bot added the Area: @shopify/app @shopify/app package issues label Aug 28, 2026

Support single-subscription events modules when reading remote config…

80e3b4b

…uration Assisted-By: devx/aa56a38c-289a-416e-8a9a-0de281e4e3e7

rezaansyed force-pushed the events-config-link-shape-tolerance branch from 33e9272 to 80e3b4b Compare September 21, 2026 12:20

Strip the materialized subscription api_version when reading remote e…

31059a0

…vents configuration Assisted-By: devx/aa56a38c-289a-416e-8a9a-0de281e4e3e7

cdarne reviewed Sep 22, 2026

View reviewed changes

Comment thread packages/app/src/cli/models/extensions/specifications/transform/app_config_events.ts Outdated

cdarne reviewed Sep 22, 2026

View reviewed changes

Comment thread packages/app/src/cli/models/extensions/specifications/transform/app_config_events.ts Outdated

address PR commments

f256c8c

This was referenced Sep 25, 2026

Prototype Events identity with specification-owned fan-in #8665

Closed

Use module identity for Events configuration round trips #8666

Closed

Prototype Events identity with a localized adapter #8667

Closed

cdarne force-pushed the events-config-link-shape-tolerance branch from 1a14973 to db2b32f Compare September 25, 2026 16:16

cdarne force-pushed the events-config-link-shape-tolerance branch from db2b32f to f07a960 Compare September 25, 2026 18:16

isaacroldan mentioned this pull request Sep 28, 2026

Expand app configuration through extension specifications #8686

Open

1 of 4 tasks

cdarne mentioned this pull request Sep 28, 2026

Fix repeated event config diffs when API versions are inherited #8690

Merged

1 of 4 tasks

isaacroldan reviewed Sep 29, 2026

View reviewed changes

isaacroldan reviewed Sep 30, 2026

View reviewed changes

isaacroldan and others added 4 commits September 30, 2026 11:43

Derive events handles from subscription data

efcaa23

Keep app selection tests unchanged

c6342b7

Remove redundant events transform tests

5b01a6e

isaacroldan marked this pull request as ready for review September 30, 2026 14:59

isaacroldan requested a review from a team as a code owner September 30, 2026 14:59

isaacroldan and others added 3 commits September 30, 2026 17:00

Remove the changeset

e89eb0d

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Merge main into events-config-link-shape-tolerance

3613aa0

github-actions Bot added no-changelog This PR doesn't include a changeset entry. Is an internal only change not relevant to end users. and removed Area: @shopify/app @shopify/app package issues labels Sep 30, 2026

dpeacock reviewed Sep 30, 2026

View reviewed changes

Comment thread packages/app/src/cli/models/extensions/specifications/transform/app_config_events.ts

Comment thread packages/app/src/cli/models/extensions/specifications/transform/app_config_events.ts Outdated

rezaansyed added 2 commits September 30, 2026 16:01

Cover merging single-subscription events modules with a shared api_ve…

d1c1a64

…rsion

rezaansyed requested review from cdarne, dpeacock and isaacroldan September 30, 2026 20:20

rezaansyed self-assigned this Sep 30, 2026

rezaansyed closed this Sep 30, 2026

rezaansyed reopened this Sep 30, 2026

dpeacock approved these changes Sep 30, 2026

View reviewed changes

isaacroldan approved these changes Oct 1, 2026

View reviewed changes

isaacroldan added this pull request to the merge queue Oct 1, 2026

Merged via the queue into main with commit 656de93 Oct 1, 2026
55 of 57 checks passed

isaacroldan deleted the events-config-link-shape-tolerance branch October 1, 2026 09:25

Navigation Menu

Support single-subscription events modules when reading remote configuration - #8425

Support single-subscription events modules when reading remote configuration#8425
isaacroldan merged 13 commits into
mainfrom
events-config-link-shape-tolerance

rezaansyed commented Aug 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

isaacroldan Sep 29, 2026

Uh oh!

rezaansyed Sep 29, 2026

Uh oh!

isaacroldan Sep 30, 2026

Uh oh!

isaacroldan Sep 30, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

rezaansyed commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

WHAT is this pull request doing?

How to test your changes?

Post-release steps

Measuring impact

Checklist

Uh oh!

Uh oh!

Uh oh!

isaacroldan Sep 29, 2026

Choose a reason for hiding this comment

Uh oh!

rezaansyed Sep 29, 2026

Choose a reason for hiding this comment

Uh oh!

isaacroldan Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

isaacroldan Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rezaansyed commented Aug 28, 2026 •

edited

Loading