Mark POS .observe extension targets as @deprecated by vctrchu · Pull Request #4146 · Shopify/ui-extensions

vctrchu · 2026-03-18T19:55:18Z

Part of https://github.com/shop/issues-retail/issues/26066

What

Adds @deprecated and @private JSDoc annotations to all 4 POS observe extension targets, pointing developers to pos.app.ready.data + window.addEventListener() as the replacement.

Targets deprecated

Observe target	Replacement
`pos.transaction-complete.event.observe`	`window.addEventListener('transactioncomplete', cb)` on `pos.app.ready.data`
`pos.cash-tracking-session-start.event.observe`	`window.addEventListener('cashtrackingsessionstart', cb)` on `pos.app.ready.data`
`pos.cash-tracking-session-complete.event.observe`	`window.addEventListener('cashtrackingsessioncomplete', cb)` on `pos.app.ready.data`
`pos.cart-update.event.observe`	`api.cart.current.subscribe()` on `pos.app.ready.data`

Why

The observe targets are fire-and-forget — they run once per event with no persistent state, no access to APIs, and no way to correlate events. pos.app.ready.data is a persistent background target that runs for the entire session, receives events via the standard window.addEventListener() Web API, and has full access to non-UI APIs (cart, storage, session, locale, connectivity, device, product search).

Notes

Annotations only — no runtime behavior changes
@private excludes these from generated shopify.dev documentation
Existing extensions using these targets continue to work unchanged
cart_update has no event equivalent in PosEventMap — cart state is continuous, not discrete, so the replacement is the subscribable api.cart.current.subscribe() pattern

Related PRs

Resolves: https://github.com/shop/issues-retail/issues/26066
Epic: https://github.com/shop/issues-retail/issues/26019

Test plan

yarn build passes
CI passes (annotations only, no runtime changes)

github-actions · 2026-03-18T19:55:26Z

🚨🚨🚨 Docs migration in progress 🚨🚨🚨

We are actively migrating UI extension reference docs to MDX in the areas/platforms/shopify-dev zone of the monorepo. This impacts docs for the following surfaces:

During this migration, please be aware of the following:

.doc.ts files are being deprecated. Changes to .doc.ts files in this repo will not be reflected in the new MDX-based docs. If you need to update docs for a reference that has already been migrated, make your changes directly in the areas/platforms/shopify-dev zone of the monorepo instead.

Doc comments in .ts source files (the comment blocks above types and functions) are also affected. Generating docs from these comments currently requires a newer version of the @shopify/generate-docs library that isn't yet available. Updates to doc comments may not produce the expected output until the migration is complete.

Examples that previously lived in this repo are being moved to the areas/platforms/shopify-dev zone of the monorepo and should be authored there going forward.

What should I do?

If your PR includes changes to .doc.ts files, doc comments, or examples, please reach out to us in #devtools-proj-templated-refs so we can help ensure your updates are captured correctly.
If your PR is limited to source code changes (non-docs), you can ignore this notice.

Thanks for your patience while we complete the migration! 🙏

@deprecated

Add @deprecated and @Private JSDoc annotations to all 4 POS observe extension targets: - pos.transaction-complete.event.observe - pos.cash-tracking-session-start.event.observe - pos.cash-tracking-session-complete.event.observe - pos.cart-update.event.observe Each annotation includes the deprecation version (2026-04), migration path to pos.app.ready.data + shopify.addEventListener(), and a link to the new target's documentation. pos.cart-update.event.observe also references shopify.cart.current.subscribe() as an alternative for render targets. Resolves: shop/issues-retail#26066 Epic: shop/issues-retail#26019 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…_update event reference

mcvinci

Hey @vctrchu! Responded to your question, and also added a couple of other comments! ❤️

mcvinci · 2026-03-31T23:05:10Z

+  /**
+   * Fires when a cash tracking session starts.
+   *
+   * @deprecated Deprecated as of `2026-04`. Use `pos.app.ready.data` target with


Shouldn't these all be deprecated as of 2025-10?

mcvinci · 2026-03-31T23:05:23Z

+   *
+   * @deprecated Deprecated as of `2026-04`. Use `pos.app.ready.data` target with
+   * `window.addEventListener('cash_tracking_session_start', callback)` instead.
+   * See https://shopify.dev/docs/api/pos-ui-extensions/unstable/targets/pos-app-ready-data


These URLs don't exist.

Fixed to use latest

…derscores)

mcvinci

Hey @vctrchu! Took another quick look, and added some further suggestions! ❤️ Thanks again for these docs!

mcvinci · 2026-04-02T20:35:42Z

+   *
+   * @deprecated Deprecated as of `2025-10`. Use `pos.app.ready.data` target with
+   * `window.addEventListener('transactioncomplete', callback)` instead.
+   * See https://shopify.dev/docs/api/pos-ui-extensions/latest/targets/pos-app-ready-data


Quick question: Is this a URL to a page that currently exists?

Let's embed the URL as part of the running text. So something like "Use the [pos.app.ready.app target](link). Also, let's use the version variable in URLs like this:

/docs/api/pos-ui-extensions/{API_VERSION}/targets/pos-app-ready-data

Good call! The pos.app.ready.data target page doesn't exist yet — it'll go live with the 2026-04 API
I've updated all 4 deprecation blocks to:

Add "the" before pos.app.ready.data ✅

Inline the URL in the text as [pos.app.ready.data target](link) instead of a separate "See" line ✅

Use {API_VERSION} variable in URLs ✅

Awesome, thanks, @vctrchu!

mcvinci

🚀

Apply suggested changes

NathanJolly · 2026-06-03T17:44:52Z

Hi @vctrchu ! Do you mind taking me off of this PR too? 🙏

…ailing newlines The deprecation annotations added in this PR cause two CI lint failures: 1. ESLint import/no-deprecated fires on the imports and usages of CashTrackingSessionStartData, CashTrackingSessionCompleteData, and CartUpdateEventData inside extension-targets.ts. These usages are intentional — extension-targets.ts is the file that defines the deprecated targets themselves, so the deprecated types must still be referenced here. Suppress the rule on each import and usage site. 2. Prettier flags three trailing blank lines at the end of CashTrackingSessionData.ts. Remove them.

The deprecation annotations referenced `2025-10` — the API version when the replacement `pos.app.ready.data` target became available — but the existing convention in this repo (see `useTarget` in checkout/preact and `useDeliveryGroupTarget`) uses "Deprecated as of version <X>" to refer to the version that introduces the deprecation itself. This PR targets `2026-07-rc`, so that is the correct version. Also match the existing convention by including the word "version" and ending each annotation with "instead." for consistency.

vctrchu self-assigned this Mar 18, 2026

js-goupil approved these changes Mar 18, 2026

View reviewed changes

vctrchu mentioned this pull request Mar 30, 2026

feat(pos): add TypeScript types for pos.app.ready.data background target #4123

Merged

vctrchu force-pushed the deprecate-observe-targets branch from df3502f to 83aff98 Compare March 31, 2026 01:12

vctrchu and others added 2 commits March 30, 2026 18:14

fix: use window.addEventListener in deprecation messages, remove cart…

7386990

…_update event reference

vctrchu force-pushed the deprecate-observe-targets branch from 83aff98 to 7386990 Compare March 31, 2026 01:14

vctrchu requested review from a team and NathanJolly March 31, 2026 01:14

vctrchu marked this pull request as ready for review March 31, 2026 02:10

fatbattk reviewed Mar 31, 2026

View reviewed changes

Comment thread packages/ui-extensions/src/surfaces/point-of-sale/extension-targets.ts

mcvinci reviewed Mar 31, 2026

View reviewed changes

vctrchu added 3 commits April 1, 2026 13:22

Address review: deprecation version 2025-10, fix doc URLs to latest

fbcbc31

Fix event names to match ui-api-design (lowercase concatenated, no un…

99ef265

…derscores)

Simplify cart deprecation wording: point to pos.app.ready.data target

4334abc

vctrchu requested review from fatbattk and mcvinci April 1, 2026 20:35

fatbattk approved these changes Apr 1, 2026

View reviewed changes

mcvinci reviewed Apr 2, 2026

View reviewed changes

Address review: inline URLs with {API_VERSION}, add 'the' article

8e9192b

mcvinci approved these changes Apr 2, 2026

View reviewed changes

vctrchu marked this pull request as draft April 9, 2026 19:56

vctrchu changed the base branch from 2026-04-rc to 2026-07-rc May 5, 2026 22:22

vctrchu and others added 4 commits May 5, 2026 15:22

Merge branch '2026-07-rc' into deprecate-observe-targets

bdb792b

Apply suggested changes

ce8141c

Apply suggested changes

Apply suggested changes

af42777

Apply suggested changes

Apply suggested changes

f5888c6

Apply suggested changes

NathanJolly mentioned this pull request May 28, 2026

feat(pos): add storage.current subscribable types to Storage interface #4235

Merged

vctrchu removed the request for review from NathanJolly June 3, 2026 18:16

Merge branch '2026-07-rc' into deprecate-observe-targets

4b938cd

github-actions Bot added the cla-needed label Jun 3, 2026

vctrchu force-pushed the deprecate-observe-targets branch from 4570355 to edfba59 Compare June 3, 2026 19:58

github-actions Bot removed the cla-needed label Jun 3, 2026

vctrchu marked this pull request as ready for review June 3, 2026 19:59

vctrchu merged commit 38976c5 into 2026-07-rc Jun 3, 2026
6 checks passed

vctrchu mentioned this pull request Jun 30, 2026

chore(pos): remove deprecated .observe event extension targets #4535

Merged

Uh oh!

Conversation

vctrchu commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Targets deprecated

Why

Notes

Related PRs

Test plan

Uh oh!

github-actions Bot commented Mar 18, 2026

🚨🚨🚨 Docs migration in progress 🚨🚨🚨

What should I do?

Uh oh!

Uh oh!

mcvinci left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mcvinci Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

mcvinci Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

vctrchu Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

mcvinci left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mcvinci Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

vctrchu Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcvinci Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mcvinci left a comment

Choose a reason for hiding this comment

Uh oh!

NathanJolly commented Jun 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

vctrchu commented Mar 18, 2026 •

edited

Loading

vctrchu Apr 2, 2026 •

edited

Loading