Ship custom element tag-name typing in the published declarations by kiftio · Pull Request #958 · Shopify/checkout-kit

kiftio · 2026-10-08T14:24:45Z

What changes are you making?

The published types lose every custom element's tag-name typing; today that means <shopify-checkout>. Each component declares its tag in a declare global { interface HTMLElementTagNameMap … } block, but API Extractor (vite-plugin-dts with rollupTypes) drops declare global when it bundles the declarations. This is a known limitation: microsoft/rushstack#1709, open since 2020, with HTMLElementTagNameMap called out in the thread. TypeScript consumers got a plain HTMLElement from document.createElement("shopify-checkout") and had to cast:

error TS2740: Type 'HTMLElement' is missing the following properties from type 'ShopifyCheckout': #private, src, logLevel, telemetry, and 10 more.

scripts/tag-name-map.ts restores it with the workaround used in #1709, made generic:

Collect: while declarations are written (beforeWriteFile), collect every component's HTMLElementTagNameMap entries from its per-file declarations, parsed with the TypeScript compiler API.
Append: after the type bundling, append one sorted augmentation to dist/index.d.ts.
Fail the build if a mapped class isn't exported from the entry (the augmentation would name a missing type), if two classes claim one tag, or if an entry has a form we can't reproduce.

New components get their typing without config changes; each component's register.ts stays the only place its tag is written.

Note

Alternative considered: replacing API Extractor with rolldown-plugin-dts, which keeps declare global and so would make this workaround unnecessary. A spike produced an identical public API (diffed with the TypeScript checker) — the same types, from a different tool — at the cost of: a pre-1.0 dependency (0.28.x) in the publish path, six config workarounds to inline the protocol package's types the way API Extractor's bundledPackages does, ~1.5 s slower builds, and (at the time) a Rolldown ≥ 1.2 requirement that Vite 8.0 did not meet. Vite 8.3 has since removed that last blocker, but the others stand, and this workaround is 120 tested lines that delete cleanly. Reassess when the plugin reaches 1.0 or the protocol-package type layout changes for other reasons.

It sits at the bottom of the Web stack so #940 builds on it directly. #940 extends the typing to the new @shopify/checkout-kit/shopify-checkout entry and adds strict consumer type tests for both import styles.

How to test

pnpm test runs the scripts/tag-name-map.test.ts unit tests (collection, sorting, the missing-export, conflicting-tag and double-append failures). Vitest now includes scripts/**/*.test.ts.
e2e typecheck as a regression guard: the e2e helpers now use HTMLElementTagNameMap["shopify-checkout"] instead of casting to the class. CI's pnpm --dir test/e2e typecheck runs against the built package, so it fails if the published typing goes missing. I verified this by removing the augmentation from dist/index.d.ts: TS2339: Property 'shopify-checkout' does not exist on type 'HTMLElementTagNameMap'.
pnpm lint, pnpm build, pnpm verify, pnpm compare-snapshot and the Playwright suite (16/16) pass.

github-actions · 2026-10-08T14:26:28Z

Bundle Size Budgets

Budget	Size	Limits	Result
Web JavaScript (uncompressed)	34.99 KiB (0 B)	35 KiB soft / 50 KiB hard	✅ Within budget

Bundle and package size

Web bundle sizes cover shipped runtime JavaScript. Package sizes cover the full published archive, including any source maps, declarations, and documentation it contains.

Platform	Measurement	Compression	Base	Head	Delta
Web	JavaScript bundle	Uncompressed	35.0 KiB	35.0 KiB	0 B
Web	JavaScript bundle	gzip	10.8 KiB	10.8 KiB	0 B
Web	npm package (`.tgz`)	gzip	93.1 KiB	93.1 KiB	+38 B

Web package files (uncompressed)

These are uncompressed file sizes; they do not sum to the compressed package size above.

File	Base	Head	Delta
`dist/index.js.map`	255.4 KiB	255.4 KiB	0 B
`dist/custom-elements.json`	51.9 KiB	51.9 KiB	0 B
`dist/index.d.ts`	48.5 KiB	48.6 KiB	+100 B
`dist/index.js`	35.0 KiB	35.0 KiB	0 B
`README.md`	21.7 KiB	21.7 KiB	0 B
`package.json`	3.6 KiB	3.6 KiB	0 B
`LICENSE`	1.1 KiB	1.1 KiB	0 B

How sizes are measured

Measured from the PR base SHA and PR head SHA. Web bundle rows sum shipped .js, .mjs, and .cjs files under dist/, excluding source maps and declarations. The gzip bundle size sums files compressed individually with gzip -n -9. npm package sizes are gzip-compressed .tgz archives; Android AAR sizes are ZIP archives. Package sizes are not final app binary sizes.

bitrise · 2026-10-08T14:31:39Z

Bitrise builds

E2E · iOS CI

Checkout Kit E2E results

No native E2E runs were selected for this change.

github-actions · 2026-10-08T14:31:50Z

Web — Coverage Report

Lines	Statements	Branches	Functions
	95.52% (427/447)	86.64% (227/262)	97.19% (104/107)

API Extractor (rollupTypes) drops `declare global` blocks, so the published declarations lost the HTMLElementTagNameMap augmentation. TypeScript consumers got a plain HTMLElement from document.createElement("shopify-checkout") and had to cast. Append the augmentation to the rolled-up dist/index.d.ts after the declaration build, and fail the build if ShopifyCheckout moves out of it.

Replace the hard-coded shopify-checkout augmentation with entries collected from each component's per-file declarations, appended once to the rolled-up entry (API Extractor drops `declare global`; microsoft/rushstack#1709). The build fails if a mapped class isn't exported from the entry or two classes claim one tag. The e2e helpers now resolve the element type through HTMLElementTagNameMap["shopify-checkout"] instead of casting to the class, so the e2e typecheck (which runs against the built package) fails if the published typing goes missing.

Locator.evaluate infers the element type from the callback parameter, so annotating it with HTMLElementTagNameMap["shopify-checkout"] replaces the casts and keeps the e2e typecheck tied to the published tag typing.

Replace vite-plugin-dts (API Extractor) with rolldown-plugin-dts, which keeps `declare global` augmentations in the bundled declarations (microsoft/rushstack#1709). The tag-name collection workaround from #958 (scripts/tag-name-map.ts and its tests) is deleted. The HTMLElementTagNameMap entry moves from register.ts to the class module it describes: both the package root and the component entry import that module, so either import types <shopify-checkout>, and the component entry declaration stays a shim onto the root as before. The custom-elements manifest is unchanged. With #961 (Vite 8.3, Rolldown >= 1.2) and #962 (protocol declarations emittable in isolation), the plugin runs on its default isolated- declarations generator with two config lines: an oxc exclude for emitted declarations and `sideEffects: true`. No tsc-mode workarounds remain. Output: one rolled-up dist/index.d.ts with the same 26 exports as before, the protocol package still inlined, no external imports. Package file set is unchanged. The full web build is ~0.8 s end to end.

Enable isolatedDeclarations for the protocol TypeScript package so every exported value carries a type that can be emitted without type inference across files: - The generated catalog (`checkoutProtocolCatalogPayloadDecoders`, `notificationDescriptors`, `requestDescriptors`) now has explicit named types instead of `satisfies`. The three new type aliases are additive. - `EmbeddedCheckoutProtocol` is annotated with `typeof` queries instead of relying on `as const` inference over shorthand properties. - Codegen passes --isolatedDeclarations to the declaration emit so the committed .d.ts files stay compliant. The committed declarations are shorter (named mapped types rather than expanded object types) but structurally identical: Checkout Kit Web's rolled-up dist/index.d.ts is byte-for-byte unchanged. This removes the protocol-package reasons that rolldown-plugin-dts needed tsc-mode workarounds for in the #958 spike.

Replace vite-plugin-dts (API Extractor) with rolldown-plugin-dts, which keeps `declare global` augmentations in the bundled declarations (microsoft/rushstack#1709). The tag-name collection workaround from #958 (scripts/tag-name-map.ts and its tests) is deleted. The HTMLElementTagNameMap entry moves from register.ts to the class module it describes: both the package root and the component entry import that module, so either import types <shopify-checkout>, and the component entry declaration stays a shim onto the root as before. The custom-elements manifest is unchanged. With #961 (Vite 8.3, Rolldown >= 1.2) and #962 (protocol declarations emittable in isolation), the plugin runs on its default isolated- declarations generator with two config lines: an oxc exclude for emitted declarations and `sideEffects: true`. No tsc-mode workarounds remain. Output: one rolled-up dist/index.d.ts with the same 26 exports as before, the protocol package still inlined, no external imports. Package file set is unchanged. The full web build is ~0.8 s end to end.

github-actions Bot added the #gsd:50662 Rebase Checkout Kit on UCP label Oct 8, 2026

kiftio added this pull request to stack #959 October 8, 2026 14:29

kiftio marked this pull request as ready for review October 8, 2026 14:31

kiftio requested a review from a team as a code owner October 8, 2026 14:31

kiftio changed the title ~~Ship the shopify-checkout tag-name typing~~ Ship custom element tag-name typing in the published declarations Oct 8, 2026

kiftio mentioned this pull request Oct 8, 2026

Organize Web components and register through component entries #940

Merged

kiftio added 3 commits October 8, 2026 20:25

Type e2e locator callbacks instead of casting the element

1f48c42

Locator.evaluate infers the element type from the callback parameter, so annotating it with HTMLElementTagNameMap["shopify-checkout"] replaces the casts and keeps the e2e typecheck tied to the published tag typing.

kiftio force-pushed the dk/web-tag-name-types branch from 1c1c658 to 1f48c42 Compare October 8, 2026 19:25

markmur approved these changes Oct 9, 2026

View reviewed changes

kiftio merged commit 4e9fee6 into main Oct 9, 2026
26 checks passed

kiftio deleted the dk/web-tag-name-types branch October 9, 2026 09:04

This was referenced Oct 9, 2026

Bump Vite to 8.3 for the web package #961

Merged

Make protocol TypeScript declarations emittable in isolation #962

Open

Bundle web declarations with rolldown-plugin-dts #964

Open

Navigation Menu

Repository navigation

Ship custom element tag-name typing in the published declarations - #958

Ship custom element tag-name typing in the published declarations#958
kiftio merged 3 commits into
mainfrom
dk/web-tag-name-types

kiftio commented Oct 8, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 8, 2026 •

edited

Loading

Uh oh!

bitrise Bot commented Oct 8, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

kiftio commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes are you making?

How to test

Uh oh!

github-actions Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Size Budgets

Bundle and package size

Uh oh!

bitrise Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bitrise builds

Checkout Kit E2E results

Uh oh!

github-actions Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Web — Coverage Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kiftio commented Oct 8, 2026 •

edited

Loading

github-actions Bot commented Oct 8, 2026 •

edited

Loading

bitrise Bot commented Oct 8, 2026 •

edited

Loading

github-actions Bot commented Oct 8, 2026 •

edited

Loading