refactor: wip

BioPhoton · BioPhoton · commit e452315ebfe9 · 2026-02-09T00:31:03.000+01:00
diff --git a/packages/plugin-axe/src/lib/axe-core-polyfilled.ts b/packages/plugin-axe/src/lib/axe-core-polyfilled.ts
@@ -2,45 +2,39 @@
  * Axe-core Polyfilled Import
  *
  * This file ensures the jsdom polyfill runs BEFORE axe-core is imported.
- * Uses dynamic import to avoid ES module hoisting issues.
+ * Static imports are evaluated in order, so the polyfill import must come first.
  *
  * WHY THIS EXISTS:
  * axe-core has side effects on import - it expects global `window` and `document` objects
  * to be available when the module is loaded. In Node.js environments, these don't exist
  * by default. This polyfill creates a virtual DOM using JSDOM and sets these globals
  * before axe-core is imported.
  *
- * HOW IT WORKS:
- * 1. Top-level code sets up JSDOM polyfill (runs immediately)
- * 2. Axe-core is imported dynamically (runs after polyfill)
- * 3. Module exports a promise that resolves to axe-core
+ * IMPORT ORDER IS CRITICAL:
+ * 1. jsdom.polyfill.ts is imported first (sets up globalThis.window and globalThis.document)
+ * 2. axe-core is imported second (now globals exist)
  *
  * IMPORT CHAIN:
- * 1. This file (sets up polyfill, then dynamically imports axe-core)
+ * 1. This file (imports polyfill, then imports axe-core)
  * 2. safe-axe-core-import.ts (re-exports for clean imports)
  *
  * USAGE:
  * Do NOT import from this file directly. Use safe-axe-core-import.ts instead.
  *
  * @see https://github.com/dequelabs/axe-core/issues/3962
  */
-import { JSDOM } from 'jsdom';
+// CRITICAL: This import MUST come before axe-core import
+// It sets up globalThis.window and globalThis.document as side effects
+// eslint-disable-next-line import/no-unassigned-import
+// Now safe to import axe-core - globals exist due to polyfill above
+// This import MUST come after the polyfill import
+import axe from 'axe-core';
+import './jsdom.polyfill.js';
 
-// Polyfill setup - runs immediately before any axe-core code
-const html = `<!DOCTYPE html>\n<html></html>`;
-const { window: jsdomWindow } = new JSDOM(html);
+// Re-export axe as default
+export default axe;
 
-// Set globals for axe-core compatibility
-// eslint-disable-next-line functional/immutable-data
-globalThis.window = jsdomWindow as unknown as Window & typeof globalThis;
-// eslint-disable-next-line functional/immutable-data
-globalThis.document = jsdomWindow.document;
-
-// Dynamic import ensures polyfill runs first
-// This cannot be a top-level await, so we export the promise
-const axePromise = import('axe-core');
-
-// Re-export types (these are compile-time only, no runtime impact)
+// Re-export all types used throughout the codebase
 export type {
   AxeResults,
   NodeResult,
@@ -50,7 +44,3 @@ export type {
   ImpactValue,
   CrossTreeSelector,
 } from 'axe-core';
-
-// Export the axe instance synchronously by awaiting at the top level
-// Top-level await is supported in ES modules
-export default (await axePromise).default;
diff --git a/packages/plugin-axe/src/lib/jsdom.polyfill.ts b/packages/plugin-axe/src/lib/jsdom.polyfill.ts
@@ -19,6 +19,7 @@
  *
  * @see https://github.com/dequelabs/axe-core/issues/3962
  */
+// @ts-expect-error - jsdom types are in devDependencies at root level
 import { JSDOM } from 'jsdom';
 
 const html = `<!DOCTYPE html>\n<html></html>`;

Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,7 @@`
`19`	`19`	`*`
`20`	`20`	`* @see https://github.com/dequelabs/axe-core/issues/3962`
`21`	`21`	`*/`
	`22`	`+// @ts-expect-error - jsdom types are in devDependencies at root level`
`22`	`23`	`import { JSDOM } from 'jsdom';`
`23`	`24`
`24`	`25`	const html = `<!DOCTYPE html>\n<html></html>`;