From 54ad04a6b15c76ab783f8069f81b99cba3ca2afb Mon Sep 17 00:00:00 2001
From: Kenneth Kalmer <kenneth.kalmer@ably.com>
Date: Thu, 30 Apr 2026 16:31:45 +0100
Subject: [PATCH] Extract inline CSS into <link> tags for crawlability

LLM/AI crawlers bail before reaching content when the document head
contains a wall of inline CSS. Replace Gatsby's `<style data-href>`
head components with `<link rel="stylesheet">` pointing at the same
already-emitted CSS files. Production-only; dev keeps inline styles
for HMR. Sandpack and any other inline `<style>` without an href are
left in place.

Mirrors the workaround in apps/voltaire (originally added there for
Total Blocking Time, same mechanism applies here). Reference:
https://github.com/gatsbyjs/gatsby/issues/1526.

The global stylesheet href is normalized through the URL constructor
before matching, so the cascade-preserving sort works whether Gatsby
emits relative paths or the absolute URLs produced when assetPrefix
is set (Heroku review apps).

On /docs/basics: head shrinks from ~247 KB to ~8 KB, body tag
reachable 30x sooner.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 gatsby-ssr.tsx | 75 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 73 insertions(+), 2 deletions(-)

diff --git a/gatsby-ssr.tsx b/gatsby-ssr.tsx
index 8da52b1e28..c34c350f36 100644
--- a/gatsby-ssr.tsx
+++ b/gatsby-ssr.tsx
@@ -1,7 +1,8 @@
 import React from 'react';
+import type { GatsbySSR } from 'gatsby';
 import { getSandpackCssText } from '@codesandbox/sandpack-react';
 
-const onRenderBody = ({ setHeadComponents }: { setHeadComponents: (components: React.ReactNode[]) => void }) => {
+const onRenderBody: GatsbySSR['onRenderBody'] = ({ setHeadComponents }) => {
   const inlineScripts: React.ReactNode[] = [];
 
   // OneTrust consent management, inspiration taken from gatsby-google-tagmanager implementation
@@ -45,10 +46,80 @@ const onRenderBody = ({ setHeadComponents }: { setHeadComponents: (components: R
   setHeadComponents(inlineScripts);
 };
 
+type StyleComponent = React.ReactElement<
+  {
+    'data-href'?: string;
+    href?: string;
+  },
+  'style'
+>;
+
+const isStyleComponent = (node: React.ReactNode): node is StyleComponent =>
+  React.isValidElement(node) && node.type === 'style';
+
+const getStyleHref = (node: StyleComponent): string | undefined => node.props?.['data-href'] ?? node.props?.href;
+
+// Only Gatsby-emitted stylesheet chunks have a data-href/href; inline styles
+// like Sandpack's do not, and must not be reordered or replaced.
+const isExtractableStyleNode = (node: React.ReactNode): node is StyleComponent =>
+  isStyleComponent(node) && getStyleHref(node) !== undefined;
+
+const isGlobalStyleNode = (node: React.ReactNode): boolean => {
+  if (!isExtractableStyleNode(node)) {
+    return false;
+  }
+  // Heroku review apps set assetPrefix, which causes Gatsby to emit absolute
+  // URLs. Normalize to a pathname so the regex matches both forms.
+  try {
+    const stylePathname = new URL(getStyleHref(node) ?? '', 'http://localhost').pathname;
+    return /^\/styles\.[a-zA-Z0-9]+\.css$/.test(stylePathname);
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Gatsby inlines all styles from the app inside a `<style/>` tag. This makes
+ * rendered HTML hostile to LLM/AI crawlers, which often bail before reaching
+ * any content because of the wall of CSS at the top of the document.
+ * Replacing each `<style data-href="…"/>` with a `<link rel="stylesheet"/>`
+ * pointing at the same already-emitted CSS file keeps styling intact while
+ * leaving the document body close to the top of the head.
+ *
+ * The same workaround is described in https://github.com/gatsbyjs/gatsby/issues/1526.
+ *
+ * Global styles sort first within the set of Gatsby-emitted stylesheet chunks
+ * to preserve cascade order; non-style head components and any inline `<style>`
+ * tags without a data-href/href (e.g. Sandpack) keep their original positions.
+ */
+const onPreRenderHTML: GatsbySSR['onPreRenderHTML'] = ({ getHeadComponents, replaceHeadComponents }) => {
+  if (process.env.NODE_ENV !== 'production') {
+    return;
+  }
+
+  const headComponents = getHeadComponents();
+  const sortedStyleComponents = headComponents
+    .filter(isExtractableStyleNode)
+    .sort((a, b) => Number(isGlobalStyleNode(b)) - Number(isGlobalStyleNode(a)));
+  let sortedStyleIndex = 0;
+
+  const transformedHeadComponents = headComponents.map((node) => {
+    if (isExtractableStyleNode(node)) {
+      const replacement = sortedStyleComponents[sortedStyleIndex++];
+      const href = getStyleHref(replacement) as string;
+      return <link key={href} href={href} rel="stylesheet" />;
+    }
+
+    return node;
+  });
+
+  replaceHeadComponents(transformedHeadComponents);
+};
+
 /**
  * Load our user state
  */
 import UserContextWrapper from './src/contexts/user-context/wrap-with-provider';
 const wrapRootElement = UserContextWrapper;
 
-export { onRenderBody, wrapRootElement };
+export { onRenderBody, onPreRenderHTML, wrapRootElement };