Feat: Fix race condition for lit components in Astro 6

Author: jlukic

CHANGELOG.md

@@ -1,4 +1,13 @@
 
+## 5.2.0
+
+### Changes
+- Inline hydration support as a blocking script instead of using Astro's `before-hydration` or `page` injection. While debugging SSR hydration issues we discovered two separate bugs:
+  1. Astro 6 doesn't emit the `before-hydration` chunk for the client build environment, causing a 404. We [contributed a fix](https://github.com/withastro/astro/pull/15904) upstream which has been merged.
+  2. Even with the Astro fix, `before-hydration` loads as a module script which can race with other module scripts that import lit-element. If lit-element evaluates first, `globalThis.litElementHydrateSupport` isn't set yet and the hydration patches are never applied, causing intermittent duplicate rendering.
+
+  This release bundles the hydration support (~13KB) and inlines it via `head-inline` as a classic blocking script, guaranteeing it executes before any module scripts.
+
 ## 5.1.3
 
 ### Bugs

dist/index.js

@@ -32,7 +32,10 @@ function index_default() {
           "head-inline",
           readFileSync(new URL("../client-shim.min.js", import.meta.url), { encoding: "utf-8" })
         );
-        injectScript("before-hydration", `import '@semantic-ui/astro-lit/hydration-support.js';`);
+        injectScript(
+          "head-inline",
+          readFileSync(new URL("../hydration-support.min.js", import.meta.url), { encoding: "utf-8" })
+        );
         addRenderer({
           name: "@semantic-ui/astro-lit",
           serverEntrypoint: "@semantic-ui/astro-lit/server.js",

hydration-support.min.js

@@ -1,6 +1,6 @@
 {
   "name": "@semantic-ui/astro-lit",
-  "version": "5.1.3",
+  "version": "5.2.0",
   "description": "Use Lit components with Astro",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -29,6 +29,7 @@
     "client-shim.js",
     "client-shim.min.js",
     "hydration-support.js",
+    "hydration-support.min.js",
     "server.js",
     "server.d.ts",
     "server-shim.js"
@@ -37,7 +38,7 @@
     "build": "npm run build:js && npm run build:types && npm run build:minify",
     "build:js": "esbuild src/index.ts src/client.ts --format=esm --bundle --platform=node --outdir=dist",
     "build:types": "tsc src/client.ts --declaration --emitDeclarationOnly --skipLibCheck --outDir ./dist",
-    "build:minify": "esbuild client-shim.js --minify --outfile=client-shim.min.js",
+    "build:minify": "esbuild client-shim.js --minify --outfile=client-shim.min.js && esbuild hydration-support.js --bundle --format=iife --minify --outfile=hydration-support.min.js",
     "dev": "npm run build -- --watch",
     "test": "node test/server.test.js && node test/sass.test.js"
   },

package.json

@@ -36,8 +36,14 @@ export default function (): AstroIntegration {
 					'head-inline',
 					readFileSync(new URL('../client-shim.min.js', import.meta.url), { encoding: 'utf-8' })
 				);
-				// Inject the hydration code, before a component is hydrated.
-				injectScript('before-hydration', `import '@semantic-ui/astro-lit/hydration-support.js';`);
+				// Inject hydration support as a blocking script to guarantee it runs
+				// before any module scripts can load lit-element. This avoids a race
+				// condition where lit-element evaluates before the hydration patches
+				// are registered on globalThis.litElementHydrateSupport.
+				injectScript(
+					'head-inline',
+					readFileSync(new URL('../hydration-support.min.js', import.meta.url), { encoding: 'utf-8' })
+				);
 				// Add the lit renderer so that Astro can understand lit components.
 				addRenderer({
 					name: '@semantic-ui/astro-lit',