chore: remove legacy globalThis polyfill

janechu · Copilot · janechu · commit 94fcc72225aa · 2026-04-22T15:23:58.000-07:00
Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
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` and can be shared across multiple versions of the library loaded on the same page.
 
+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
@@ -1,5 +1,21 @@
 # Migrating from previous versions
 
+## 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.92 KB | 19.57 KB | 17.56 KB |
-| FASTElement | 25.29 KB | 7.94 KB | 7.17 KB |
-| Updates | 3.61 KB | 1.48 KB | 1.26 KB |
-| Observable | 8.12 KB | 2.99 KB | 2.66 KB |
-| observable | 8.16 KB | 3.00 KB | 2.68 KB |
-| attr | 3.55 KB | 1.42 KB | 1.19 KB |
-| children | 6.15 KB | 2.34 KB | 2.06 KB |
-| css | 11.32 KB | 4.08 KB | 3.67 KB |
-| ref | 5.12 KB | 2.02 KB | 1.76 KB |
-| slotted | 5.94 KB | 2.28 KB | 2.00 KB |
-| volatile | 8.22 KB | 3.02 KB | 2.69 KB |
+| CDN Rollup Bundle | 65.65 KB | 19.50 KB | 17.51 KB |
+| FASTElement | 25.05 KB | 7.87 KB | 7.10 KB |
+| Updates | 3.37 KB | 1.41 KB | 1.18 KB |
+| Observable | 7.89 KB | 2.92 KB | 2.59 KB |
+| observable | 7.92 KB | 2.93 KB | 2.60 KB |
+| attr | 3.32 KB | 1.34 KB | 1.11 KB |
+| children | 5.91 KB | 2.27 KB | 2.00 KB |
+| css | 11.08 KB | 4.01 KB | 3.59 KB |
+| ref | 4.88 KB | 1.94 KB | 1.69 KB |
+| slotted | 5.70 KB | 2.20 KB | 1.93 KB |
+| volatile | 7.98 KB | 2.95 KB | 2.62 KB |
 | when | 2.33 KB | 956 B | 771 B |
-| html | 28.18 KB | 9.29 KB | 8.35 KB |
-| repeat | 31.97 KB | 10.19 KB | 9.19 KB |
+| html | 27.95 KB | 9.22 KB | 8.28 KB |
+| repeat | 31.73 KB | 10.13 KB | 9.12 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.92 KB | 19.57 KB | 17.56 KB |
-| FASTElement | 25.29 KB | 7.94 KB | 7.17 KB |
-| Updates | 3.61 KB | 1.48 KB | 1.26 KB |
-| Observable | 8.12 KB | 2.99 KB | 2.66 KB |
-| observable | 8.16 KB | 3.00 KB | 2.68 KB |
-| attr | 3.55 KB | 1.42 KB | 1.19 KB |
-| children | 6.15 KB | 2.34 KB | 2.06 KB |
-| css | 11.32 KB | 4.08 KB | 3.67 KB |
-| ref | 5.12 KB | 2.02 KB | 1.76 KB |
-| slotted | 5.94 KB | 2.28 KB | 2.00 KB |
-| volatile | 8.22 KB | 3.02 KB | 2.69 KB |
+| CDN Rollup Bundle | 65.65 KB | 19.50 KB | 17.51 KB |
+| FASTElement | 25.05 KB | 7.87 KB | 7.10 KB |
+| Updates | 3.37 KB | 1.41 KB | 1.18 KB |
+| Observable | 7.89 KB | 2.92 KB | 2.59 KB |
+| observable | 7.92 KB | 2.93 KB | 2.60 KB |
+| attr | 3.32 KB | 1.34 KB | 1.11 KB |
+| children | 5.91 KB | 2.27 KB | 2.00 KB |
+| css | 11.08 KB | 4.01 KB | 3.59 KB |
+| ref | 4.88 KB | 1.94 KB | 1.69 KB |
+| slotted | 5.70 KB | 2.20 KB | 1.93 KB |
+| volatile | 7.98 KB | 2.95 KB | 2.62 KB |
 | when | 2.33 KB | 956 B | 771 B |
-| html | 28.18 KB | 9.29 KB | 8.35 KB |
-| repeat | 31.97 KB | 10.19 KB | 9.19 KB |
+| html | 27.95 KB | 9.22 KB | 8.28 KB |
+| repeat | 31.73 KB | 10.13 KB | 9.12 KB |
