fix: prevent frames of pre-styled content with EXPERIMENTAL_CSS_SUSPENSE

Author: katywings

packages/start/src/shared/assets.ts

@@ -1,10 +1,10 @@
-import { createRenderEffect, createResource, JSX, onCleanup, sharedConfig } from "solid-js";
+import { createRenderEffect, createResource, onCleanup, sharedConfig } from "solid-js";
 import { getRequestEvent, isServer, useAssets as useAssets_ } from "solid-js/web";
 import { renderAsset, type Asset } from "../server/renderAsset.tsx";
 
 /**
  * Keep's Solid suspended while loading CSS
- * Prevents FOUC's
+ * Prevents FOUC's for uncached CSS
  */
 const EXPERIMENTAL_CSS_SUSPENSE = true;
 
@@ -19,7 +19,13 @@ const CANCEL_EVENT = "cancel";
 const EVENT_REGISTRY = Symbol("assetRegistry");
 const NOOP = () => "";
 
-type AssetEntity = { key: string; consumers: number; el?: HTMLElement; ssrIdx?: number };
+type AssetEntity = {
+  key: string;
+  consumers: number;
+  el?: HTMLElement;
+  preloadEl?: HTMLLinkElement;
+  ssrIdx?: number;
+};
 type Registry = Record<string, AssetEntity>;
 type AttrKeys = keyof Asset["attrs"];
 
@@ -53,7 +59,7 @@ export const useAssets = (assets: Asset[], nonce?: string) => {
   const cssKeys: string[] = [];
 
   const cssSuspense = EXPERIMENTAL_CSS_SUSPENSE && !sharedConfig.context;
-  const cssPromises: Promise<any>[] = [];
+  const preloadPromises: Promise<{ placeholderEl: Text; entity: AssetEntity }>[] = [];
 
   for (const asset of assets) {
     const entity = getEntity(registry, asset);
@@ -72,40 +78,52 @@ export const useAssets = (assets: Asset[], nonce?: string) => {
       entity.ssrIdx = ssrRequestAssets.length - 1;
     } else {
       const el = (entity.el = document.createElement(asset.tag));
-
-      if (cssSuspense && isCSSLink) {
-        cssPromises.push(
-          new Promise(res => {
-            el.addEventListener("load", res, { once: true });
-            el.addEventListener(CANCEL_EVENT, res, { once: true });
-            el.addEventListener("error", res, { once: true });
-          })
-        );
-      }
-
       if (EXPERIMENTAL_BLOCKING && isCSS) {
         el.setAttribute("blocking", "render");
       }
-
       for (const k of Object.keys(asset.attrs)) {
         if (k === "key") continue;
         el.setAttribute(k, asset.attrs[k as AttrKeys]);
       }
-
       if ("children" in asset) {
         el.innerHTML = asset.children as string;
       }
 
-      document.head.appendChild(el);
+      if (cssSuspense && isCSS) {
+        const placeholderEl = document.createTextNode("");
+        document.head.appendChild(placeholderEl);
+
+        preloadPromises.push(
+          (async () => {
+            if (isCSSLink && asset.attrs.href) {
+              const preloadEl = (entity.preloadEl = preloadStyle(asset.attrs.href));
+              await new Promise(res => {
+                ["load", "error", CANCEL_EVENT].map(t => preloadEl.addEventListener(t, res));
+              });
+            }
+
+            return { placeholderEl, entity };
+          })()
+        );
+      } else {
+        document.head.appendChild(el);
+      }
     }
   }
 
-  if (cssSuspense && cssPromises.length) {
-    const [r] = createResource(() => Promise.all(cssPromises));
-    createRenderEffect(r);
+  if (cssSuspense && preloadPromises.length) {
+    const [r] = createResource(() => Promise.all(preloadPromises));
+    createRenderEffect(() => {
+      const preloads = r();
+      if (!preloads) return;
+
+      for (const { entity, placeholderEl } of preloads) {
+        if (!entity.consumers || !entity.el) continue;
+        placeholderEl.replaceWith(entity.el);
+      }
+    });
   }
 
-  // Unmounting logic
   onCleanup(() => {
     for (const key of cssKeys) {
       const entity = registry[key]!;
@@ -118,28 +136,25 @@ export const useAssets = (assets: Asset[], nonce?: string) => {
         // Ideally this logic should be implemented directly in dom-expressions
         ssrRequestAssets.splice(entity.ssrIdx!, 1, NOOP);
       } else {
-        if (EXPERIMENTAL_CSS_SUSPENSE) entity.el!.dispatchEvent(new CustomEvent(CANCEL_EVENT));
+        if (entity.preloadEl) {
+          entity.preloadEl.dispatchEvent(new CustomEvent(CANCEL_EVENT));
+          entity.preloadEl.remove();
+        }
         entity.el!.remove();
         delete registry[key];
       }
     }
   });
 };
 
-export const preloadStyles = (assets: Asset[]) => {
-  if (import.meta.env.SSR) return;
-  for (const asset of assets) {
-    const attrs = asset.attrs as JSX.LinkHTMLAttributes<HTMLLinkElement>;
-    if (!attrs.href || attrs.rel !== "stylesheet") return;
-
-    let element = document.head.querySelector(`link[href="${attrs.href}"]`);
-    if (element) return;
-
-    // create a link preload element for the css file so it starts loading but doesnt get attached
-    element = document.createElement("link");
-    element.setAttribute("rel", "preload");
-    element.setAttribute("as", "style");
-    element.setAttribute("href", attrs.href);
-    document.head.appendChild(element);
-  }
+const preloadStyle = (href: string) => {
+  const element = document.createElement("link");
+
+  element.setAttribute("rel", "preload");
+  element.setAttribute("as", "style");
+  element.setAttribute("href", href);
+
+  document.head.appendChild(element);
+
+  return element;
 };

packages/start/src/shared/lazy.ts

@@ -2,7 +2,7 @@ import { Component, createComponent, lazy as solidLazy } from "solid-js";
 import { getRequestEvent } from "solid-js/web";
 import { getManifest } from "solid-start:get-manifest";
 import { Asset } from "../server/types.ts";
-import { preloadStyles, useAssets } from "./assets.ts";
+import { useAssets } from "./assets.ts";
 
 const assetsById: Record<string, Asset[]> = {};
 
@@ -32,8 +32,6 @@ const collectAssets = function <T extends () => Promise<{ default: Component<any
     const assets: Asset[] = await getAssets(id);
     if (!assets.length) return mod;
 
-    preloadStyles(assets);
-
     return {
       default: (props: any) => {
         // TODO: How to get nonce on the client