chore: remove legacy globalThis polyfill (#7481)

janechu · web-flow · commit bd4550aeaa55 · 2026-04-22T19:04:22.000-07:00
# Pull Request ## 📖 Description - Remove the legacy `globalThis` polyfill from `@microsoft/fast-element` while keeping the `requestIdleCallback` / `cancelIdleCallback` fallback. - Document the new v3 runtime expectation in `README.md`, `DESIGN.md`, `MIGRATION.md`, and the 3.x browser support page. - Regenerate the fast-element size docs to capture the smaller bundle output. ### 🎫 Issues - Closes #7289 ## 👩‍💻 Reviewer Notes - The only runtime code change is in `packages/fast-element/src/polyfills.ts`; the remaining edits are documentation, migration guidance, the change file, and generated size docs. - `npm run test` still hits an existing `@microsoft/fast-html` `nested-elements` failure on this branch, and `npm run test -w @microsoft/fast-element` still sees existing Playwright connection-refused / flaky failures unrelated to this polyfill removal. ## 📑 Test Plan - `npm run build` - `npm run biome:check` - `npm run checkchange` - `node --input-type=module -e "delete globalThis.requestIdleCallback; delete globalThis.cancelIdleCallback; await import('./packages/fast-element/dist/esm/polyfills.js'); console.log(typeof globalThis.requestIdleCallback, typeof globalThis.cancelIdleCallback);"` - `npm run test` *(currently fails in pre-existing `packages/fast-html/test/fixtures/scenarios/nested-elements/nested-elements.spec.ts`)* - `npm run test -w @microsoft/fast-element` *(currently fails in existing Playwright instability / `ERR_CONNECTION_REFUSED` cases on this branch)* ## ✅ Checklist ### General - [x] I have included a change request file using `$ npm run change` - [ ] I have added tests for my changes. - [ ] I have tested my changes. - [x] I have updated the project documentation to reflect my changes. - [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/main/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/main/CODE_OF_CONDUCT.md#our-standards) for this project.
diff --git a/change/@microsoft-fast-element-e0df8ba4-3d6c-4d95-a987-c3fcf719d9f6.json b/change/@microsoft-fast-element-e0df8ba4-3d6c-4d95-a987-c3fcf719d9f6.json
@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "Remove the built-in globalThis polyfill; fast-element v3 now requires native globalThis",
+  "packageName": "@microsoft/fast-element",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/fast-element/DESIGN.md b/packages/fast-element/DESIGN.md
@@ -50,6 +50,10 @@ For deep dives into specific areas, see the linked detailed documents.
 
 The library's kernel (the `FAST` global, the `Updates` queue, and the `Observable` system) is stored on `globalThis.FAST`.
 
+The v3 runtime assumes native `globalThis`. `src/polyfills.ts` only backfills
+`requestIdleCallback` / `cancelIdleCallback`, so applications targeting older
+engines must install their own `globalThis` polyfill before FAST loads.
+
 ---
 
 ## Core Concepts
diff --git a/packages/fast-element/MIGRATION.md b/packages/fast-element/MIGRATION.md
@@ -13,6 +13,22 @@
 1. Remove any runtime checks that read `FAST.versions`.
 2. Fix duplicate FAST installs in your bundler or dependency graph instead of relying on version tracking at runtime.
 
+## Native `globalThis` requirement (v2 → v3)
+
+### Changed behavior
+
+- **Native `globalThis` required**: `@microsoft/fast-element` no longer installs
+  a `globalThis` polyfill as a side effect. The package only keeps the
+  `requestIdleCallback` / `cancelIdleCallback` fallback for environments that
+  still lack those APIs.
+
+### Migration steps
+
+1. Verify that the browsers and JS runtimes you support provide native
+   `globalThis`.
+2. If you still target an older runtime without `globalThis`, load that
+   polyfill before importing `@microsoft/fast-element`.
+
 ## Prerendered Content Optimization (v2 → v3)
 
 ### Removed exports
diff --git a/packages/fast-element/README.md b/packages/fast-element/README.md
@@ -53,6 +53,14 @@ For simplicity, examples throughout the documentation will assume the library ha
 Looking for a quick guide on building components?  Check out [our Cheat Sheet](../resources/cheat-sheet.md#building-components).
 :::
 
+## Browser Requirements
+
+FAST Element v3 assumes a modern runtime with native `globalThis`. The package
+still installs its `requestIdleCallback` / `cancelIdleCallback` fallback
+internally, but it no longer patches `globalThis` for older engines. If you
+need to support an environment without `globalThis`, load that polyfill before
+importing `@microsoft/fast-element`.
+
 ## Export Sizes
 
 Bundle sizes for each tree-shakeable export are tracked in [`SIZES.md`](./SIZES.md) and regenerated on every build. See the [Export Sizes](https://www.fast.design/docs/3.x/resources/export-sizes/) documentation page for the latest numbers.
@@ -104,4 +112,3 @@ FASTElement.define(MyComponent, { name: "my-component" }, [logger()]);
 ```
 
 Each extension receives the full `FASTElementDefinition`, which includes the resolved element name, type, template, styles, and attribute metadata. Extensions run before `customElements.define()`, so any setup they perform is available when existing DOM elements are upgraded.
-
diff --git a/packages/fast-element/SIZES.md b/packages/fast-element/SIZES.md
@@ -4,17 +4,17 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| CDN Rollup Bundle | 65.03 KB | 19.31 KB | 17.30 KB |
-| FASTElement | 23.92 KB | 7.48 KB | 6.76 KB |
-| Updates | 3.69 KB | 1.51 KB | 1.28 KB |
-| Observable | 8.20 KB | 3.01 KB | 2.68 KB |
-| observable | 8.24 KB | 3.02 KB | 2.69 KB |
-| attr | 3.63 KB | 1.44 KB | 1.21 KB |
-| children | 6.22 KB | 2.37 KB | 2.08 KB |
-| css | 11.40 KB | 4.10 KB | 3.69 KB |
-| ref | 5.20 KB | 2.04 KB | 1.78 KB |
-| slotted | 6.01 KB | 2.30 KB | 2.02 KB |
-| volatile | 8.29 KB | 3.04 KB | 2.71 KB |
+| CDN Rollup Bundle | 64.76 KB | 19.24 KB | 17.23 KB |
+| FASTElement | 23.69 KB | 7.41 KB | 6.68 KB |
+| Updates | 3.45 KB | 1.43 KB | 1.21 KB |
+| Observable | 7.96 KB | 2.94 KB | 2.61 KB |
+| observable | 8.00 KB | 2.95 KB | 2.63 KB |
+| attr | 3.39 KB | 1.37 KB | 1.13 KB |
+| children | 5.99 KB | 2.29 KB | 2.01 KB |
+| css | 11.16 KB | 4.03 KB | 3.61 KB |
+| ref | 4.96 KB | 1.96 KB | 1.71 KB |
+| slotted | 5.78 KB | 2.23 KB | 1.95 KB |
+| volatile | 8.05 KB | 2.97 KB | 2.64 KB |
 | when | 2.40 KB | 978 B | 786 B |
-| html | 27.37 KB | 8.95 KB | 8.02 KB |
-| repeat | 31.03 KB | 9.88 KB | 8.88 KB |
+| html | 27.13 KB | 8.88 KB | 7.96 KB |
+| repeat | 30.79 KB | 9.81 KB | 8.82 KB |
diff --git a/packages/fast-element/src/polyfills.ts b/packages/fast-element/src/polyfills.ts
@@ -1,29 +1,3 @@
-/* eslint-disable @typescript-eslint/ban-ts-comment */
-(function ensureGlobalThis() {
-    if (typeof globalThis !== "undefined") {
-        // We're running in a modern environment.
-        return;
-    }
-
-    // @ts-ignore
-    if (typeof global !== "undefined") {
-        // We're running in NodeJS
-        // @ts-ignore
-        global.globalThis = global;
-    } else if (typeof self !== "undefined") {
-        (self as any).globalThis = self;
-    } else if (typeof window !== "undefined") {
-        // We're running in the browser's main thread.
-        (window as any).globalThis = window;
-    } else {
-        // Hopefully we never get here...
-        // Not all environments allow eval and Function. Use only as a last resort:
-        // eslint-disable-next-line no-new-func
-        const result = new Function("return this")();
-        result.globalThis = result;
-    }
-})();
-
 (function requestIdleCallbackPolyfill() {
     if ("requestIdleCallback" in globalThis) {
         return;
@@ -39,7 +13,7 @@
      */
     globalThis.requestIdleCallback = function requestIdleCallback(
         callback: (deadline: IdleDeadline) => void,
-        options?: { timeout: number }
+        options?: { timeout: number },
     ): number {
         const start = Date.now();
         return setTimeout(() => {
@@ -59,7 +33,7 @@
      * @public
      */
     globalThis.cancelIdleCallback = function cancelIdleCallback(
-        id: ReturnType<typeof globalThis.requestIdleCallback | typeof setTimeout>
+        id: ReturnType<typeof globalThis.requestIdleCallback | typeof setTimeout>,
     ): void {
         clearTimeout(id);
     };
diff --git a/sites/website/src/docs/3.x/resources/browser-support.md b/sites/website/src/docs/3.x/resources/browser-support.md
@@ -8,21 +8,25 @@ eleventyNavigation:
   title: Browser Support
 navigationOptions:
   activeKey: browser-support3x
-description: View the list of browsers that have native support for the Web Components features used by fast-element.
+description: View the list of browsers that have native support for the Web Components features and native globalThis required by fast-element v3.
 keywords:
   - browser support
 ---
 
-The following browsers have native support for the Web Components features used by `@microsoft/fast-element`:
+The following browsers have native support for the Web Components features used by `@microsoft/fast-element`, including the native `globalThis` required by v3:
 
 * Microsoft Edge 79+
-* Mozilla Firefox 63+
-* Google Chrome 67+
-* Apple Safari 10.1+
-* Opera 41+
-* iOS Safari 10.3+
+* Mozilla Firefox 65+
+* Google Chrome 71+
+* Apple Safari 12.1+
+* Opera 58+
+* iOS Safari 12.2+
 * Android Browser 81+
-* Opera Mobile 46+
+* Opera Mobile 54+
 * Chrome for Android 81+
 * Firefox for Android 68+
-* Samsung Internet 6.2+x
+* Samsung Internet 10.0+
+
+FAST Element v3 no longer polyfills `globalThis` for older engines. If you need
+to support an environment below these minimums, load a `globalThis` polyfill
+before importing FAST.
diff --git a/sites/website/src/docs/3.x/resources/export-sizes.md b/sites/website/src/docs/3.x/resources/export-sizes.md
@@ -19,17 +19,17 @@ Bundle sizes for `@microsoft/fast-element` exports.
 
 | Export | Minified | Gzip | Brotli |
 |--------|----------|------|--------|
-| CDN Rollup Bundle | 65.03 KB | 19.31 KB | 17.30 KB |
-| FASTElement | 23.92 KB | 7.48 KB | 6.76 KB |
-| Updates | 3.69 KB | 1.51 KB | 1.28 KB |
-| Observable | 8.20 KB | 3.01 KB | 2.68 KB |
-| observable | 8.24 KB | 3.02 KB | 2.69 KB |
-| attr | 3.63 KB | 1.44 KB | 1.21 KB |
-| children | 6.22 KB | 2.37 KB | 2.08 KB |
-| css | 11.40 KB | 4.10 KB | 3.69 KB |
-| ref | 5.20 KB | 2.04 KB | 1.78 KB |
-| slotted | 6.01 KB | 2.30 KB | 2.02 KB |
-| volatile | 8.29 KB | 3.04 KB | 2.71 KB |
+| CDN Rollup Bundle | 64.76 KB | 19.24 KB | 17.23 KB |
+| FASTElement | 23.69 KB | 7.41 KB | 6.68 KB |
+| Updates | 3.45 KB | 1.43 KB | 1.21 KB |
+| Observable | 7.96 KB | 2.94 KB | 2.61 KB |
+| observable | 8.00 KB | 2.95 KB | 2.63 KB |
+| attr | 3.39 KB | 1.37 KB | 1.13 KB |
+| children | 5.99 KB | 2.29 KB | 2.01 KB |
+| css | 11.16 KB | 4.03 KB | 3.61 KB |
+| ref | 4.96 KB | 1.96 KB | 1.71 KB |
+| slotted | 5.78 KB | 2.23 KB | 1.95 KB |
+| volatile | 8.05 KB | 2.97 KB | 2.64 KB |
 | when | 2.40 KB | 978 B | 786 B |
-| html | 27.37 KB | 8.95 KB | 8.02 KB |
-| repeat | 31.03 KB | 9.88 KB | 8.88 KB |
+| html | 27.13 KB | 8.88 KB | 7.96 KB |
+| repeat | 30.79 KB | 9.81 KB | 8.82 KB |
