Render async SolidJS components (#6791)

* Render async SolidJS components

* Add renderer-specific hydration script to allow for proper SolidJS hydration

* Add support for Solid.js 1.8.x

* Address documentation feedback

* Rebuild pnpm lock file based on main branch

* Address PR feedback from ematipico

---------

Co-authored-by: Johannes Spohr <johannes.spohr@futurice.com>
Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>

.changeset/chilly-badgers-push.md

@@ -0,0 +1,31 @@
+---
+'@astrojs/solid-js': major
+---
+
+Render SolidJS components using [`renderToStringAsync`](https://www.solidjs.com/docs/latest#rendertostringasync).
+
+This changes the renderer of SolidJS components from `renderToString` to `renderToStringAsync`. It also injects the actual SolidJS hydration script generated by [`generateHydrationScript`](https://www.solidjs.com/guides/server#hydration-script), so that [`Suspense`](https://www.solidjs.com/docs/latest#suspense), [`ErrorBoundary`](https://www.solidjs.com/docs/latest#errorboundary) and similar components can be hydrated correctly.
+
+The server render phase will now wait for Suspense boundaries to resolve instead of always rendering the Suspense fallback.
+
+If you use the APIs [`createResource`](https://www.solidjs.com/docs/latest#createresource) or [`lazy`](https://www.solidjs.com/docs/latest#lazy), their functionalities will now be executed on the server side, not just the client side.
+
+This increases the flexibility of the SolidJS integration. Server-side components can now safely fetch remote data, call async Astro server functions like `getImage()` or load other components dynamically. Even server-only components that do not hydrate in the browser will benefit.
+
+It is very unlikely that a server-only component would have used the Suspense feature until now, so this should not be a breaking change for server-only components.
+
+This could be a breaking change for components that meet the following conditions:
+
+- The component uses Suspense APIs like `Suspense`, `lazy` or `createResource`, and
+- The component is mounted using a *hydrating* directive:
+  - `client:load`
+  - `client:idle`
+  - `client:visible`
+  - `client:media`
+
+These components will now first try to resolve the Suspense boundaries on the server side instead of the client side.
+
+If you do not want Suspense boundaries to be resolved on the server (for example, if you are using createResource to do an HTTP fetch that relies on a browser-side cookie), you may consider:
+
+- changing the template directive to `client:only` to skip server side rendering completely
+- use APIs like [isServer](https://www.solidjs.com/docs/latest/api#isserver) or `onMount()` to detect server mode and render a server fallback without using Suspense.

packages/astro/e2e/shared-component-tests.js

@@ -1,7 +1,7 @@
 import { expect } from '@playwright/test';
 import { scrollToElement, testFactory, waitForHydrate } from './test-utils.js';
 
-export function prepareTestFactory(opts) {
+export function prepareTestFactory(opts, { canReplayClicks = false } = {}) {
 	const test = testFactory(opts);
 
 	let devServer;
@@ -104,7 +104,16 @@ export function prepareTestFactory(opts) {
 			await waitForHydrate(page, counter);
 
 			await inc.click();
-			await expect(count, 'count incremented by 1').toHaveText('1');
+
+			if (canReplayClicks) {
+				// SolidJS has a hydration script that automatically captures
+				// and replays click and input events on Hydration:
+				// https://www.solidjs.com/docs/latest#hydrationscript
+				// so in total there are two click events.
+				await expect(count, 'count incremented by 2').toHaveText('2');
+			} else {
+				await expect(count, 'count incremented by 1').toHaveText('1');
+			}
 		});
 
 		test('client:only', async ({ page, astro }) => {

packages/astro/e2e/solid-component.test.js

@@ -1,6 +1,11 @@
 import { prepareTestFactory } from './shared-component-tests.js';
 
-const { test, createTests } = prepareTestFactory({ root: './fixtures/solid-component/' });
+const { test, createTests } = prepareTestFactory(
+	{ root: './fixtures/solid-component/' },
+	{
+		canReplayClicks: true,
+	}
+);
 
 const config = {
 	componentFilePath: './src/components/SolidComponent.jsx',

packages/astro/src/@types/astro.ts

@@ -2293,6 +2293,18 @@ export interface SSRLoadedRenderer extends AstroRenderer {
 			attrs?: Record<string, string>;
 		}>;
 		supportsAstroStaticSlot?: boolean;
+		/**
+		 * If provided, Astro will call this function and inject the returned
+		 * script in the HTML before the first component handled by this renderer.
+		 *
+		 * This feature is needed by some renderers (in particular, by Solid). The
+		 * Solid official hydration script sets up a page-level data structure.
+		 * It is mainly used to transfer data between the server side render phase
+		 * and the browser application state. Solid Components rendered later in
+		 * the HTML may inject tiny scripts into the HTML that call into this
+		 * page-level data structure.
+		 */
+		renderHydrationScript?: () => string;
 	};
 }
 
@@ -2512,6 +2524,12 @@ export interface SSRResult {
  */
 export interface SSRMetadata {
 	hasHydrationScript: boolean;
+	/**
+	 * Names of renderers that have injected their hydration scripts
+	 * into the current page. For example, Solid SSR needs a hydration
+	 * script in the page HTML before the first Solid component.
+	 */
+	rendererSpecificHydrationScripts: Set<string>;
 	hasDirectives: Set<string>;
 	hasRenderedHead: boolean;
 	headInTree: boolean;

packages/astro/src/core/render/result.ts

@@ -274,6 +274,7 @@ export function createResult(args: CreateResultArgs): SSRResult {
 		response,
 		_metadata: {
 			hasHydrationScript: false,
+			rendererSpecificHydrationScripts: new Set(),
 			hasRenderedHead: false,
 			hasDirectives: new Set(),
 			headInTree: false,

packages/astro/src/runtime/server/render/common.ts

@@ -89,6 +89,16 @@ function stringifyChunk(
 				}
 				return renderAllHeadContent(result);
 			}
+			case 'renderer-hydration-script': {
+				const { rendererSpecificHydrationScripts } = result._metadata;
+				const { rendererName } = instruction;
+
+				if (!rendererSpecificHydrationScripts.has(rendererName)) {
+					rendererSpecificHydrationScripts.add(rendererName);
+					return instruction.render();
+				}
+				return '';
+			}
 			default: {
 				throw new Error(`Unknown chunk type: ${(chunk as any).type}`);
 			}

packages/astro/src/runtime/server/render/component.ts

@@ -375,6 +375,15 @@ If you're still stuck, please open an issue on GitHub or join us at https://astr
 				}
 			}
 			destination.write(createRenderInstruction({ type: 'directive', hydration }));
+			if (hydration.directive !== 'only' && renderer?.ssr.renderHydrationScript) {
+				destination.write(
+					createRenderInstruction({
+						type: 'renderer-hydration-script',
+						rendererName: renderer.name,
+						render: renderer.ssr.renderHydrationScript,
+					})
+				);
+			}
 			destination.write(markHTMLString(renderElement('astro-island', island, false)));
 		},
 	};

packages/astro/src/runtime/server/render/instruction.ts

@@ -11,6 +11,16 @@ export type RenderHeadInstruction = {
 	type: 'head';
 };
 
+/**
+ * Render a renderer-specific hydration script before the first component of that
+ * framework
+ */
+export type RendererHydrationScriptInstruction = {
+	type: 'renderer-hydration-script';
+	rendererName: string;
+	render: () => string;
+};
+
 export type MaybeRenderHeadInstruction = {
 	type: 'maybe-head';
 };
@@ -18,11 +28,15 @@ export type MaybeRenderHeadInstruction = {
 export type RenderInstruction =
 	| RenderDirectiveInstruction
 	| RenderHeadInstruction
-	| MaybeRenderHeadInstruction;
+	| MaybeRenderHeadInstruction
+	| RendererHydrationScriptInstruction;
 
 export function createRenderInstruction(
 	instruction: RenderDirectiveInstruction
 ): RenderDirectiveInstruction;
+export function createRenderInstruction(
+	instruction: RendererHydrationScriptInstruction
+): RendererHydrationScriptInstruction;
 export function createRenderInstruction(instruction: RenderHeadInstruction): RenderHeadInstruction;
 export function createRenderInstruction(
 	instruction: MaybeRenderHeadInstruction

packages/astro/test/fixtures/solid-component/src/components/Counter.jsx

@@ -0,0 +1,34 @@
+// Based on reproduction from https://github.com/withastro/astro/issues/6912
+
+import { For, Match, Switch } from 'solid-js';
+
+export default function Counter(props) {
+	return (
+		<For each={[1, 2, 3, 4]}>
+			{(page) => {
+				return (
+					<Switch>
+						<Match when={page % 2 === 0}>
+							<button
+								onClick={() => {
+									console.log(page);
+								}}
+							>
+								even {page}
+							</button>
+						</Match>
+						<Match when={page % 2 === 1}>
+							<button
+								onClick={() => {
+									console.log(page);
+								}}
+							>
+								odd {page}
+							</button>
+						</Match>
+					</Switch>
+				);
+			}}
+		</For>
+	);
+}

packages/astro/test/fixtures/solid-component/src/components/LazyCounter.jsx

@@ -0,0 +1,5 @@
+// Based on reproduction from https://github.com/withastro/astro/issues/6912
+
+import { lazy } from 'solid-js';
+
+export const LazyCounter = lazy(() => import('./Counter'));

packages/astro/test/fixtures/solid-component/src/components/async-components.jsx

@@ -0,0 +1,70 @@
+import { createResource, createSignal, createUniqueId, ErrorBoundary, Show } from 'solid-js';
+
+// It may be good to try short and long sleep times.
+// But short is faster for testing.
+const SLEEP_MS = 10;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export function AsyncComponent(props) {
+	const id = createUniqueId();
+
+	const [data] = createResource(async () => {
+		// console.log("Start rendering async component " + props.title);
+		await sleep(props.delay ?? SLEEP_MS);
+		// console.log("Finish rendering async component " + props.title);
+		return 'Async result for component id=' + id;
+	});
+
+	const [show, setShow] = createSignal(false);
+
+	return (
+		<div data-name="AsyncComponent" style={{ border: 'black solid 1px', padding: '4px' }}>
+			{'title=' + (props.title ?? '(none)') + ' '}
+			{'id=' + id + ' '}
+			<span>{data()}</span>{' '}
+			<button
+				type="button"
+				disabled={show()}
+				onClick={() => {
+					setShow(true);
+				}}
+			>
+				Show children
+			</button>
+			{/* NOTE: The props.children are intentionally hidden by default 
+		      to simulate a situation where hydration script might not 
+					be injected in the right spot. */}
+			<Show when={show()}>{props.children ?? 'Empty'}</Show>
+		</div>
+	);
+}
+
+export function AsyncErrorComponent() {
+	const [data] = createResource(async () => {
+		await sleep(SLEEP_MS);
+		throw new Error('Async error thrown!');
+	});
+
+	return <div>{data()}</div>;
+}
+
+export function AsyncErrorInErrorBoundary() {
+	return (
+		<ErrorBoundary fallback={<div>Async error boundary fallback</div>}>
+			<AsyncErrorComponent />
+		</ErrorBoundary>
+	);
+}
+
+export function SyncErrorComponent() {
+	throw new Error('Sync error thrown!');
+}
+
+export function SyncErrorInErrorBoundary() {
+	return (
+		<ErrorBoundary fallback={<div>Sync error boundary fallback</div>}>
+			<SyncErrorComponent />
+		</ErrorBoundary>
+	);
+}

packages/astro/test/fixtures/solid-component/src/components/defer.astro

@@ -0,0 +1,7 @@
+---
+import { AsyncComponent } from './async-components.jsx';
+
+await new Promise((resolve) => setTimeout(resolve, Astro.props.delay));
+---
+
+<AsyncComponent client:load />

packages/astro/test/fixtures/solid-component/src/pages/deferred.astro

@@ -0,0 +1,11 @@
+---
+import Defer from '../components/defer.astro';
+---
+
+<html>
+	<head><title>Solid</title></head>
+	<body>
+		<Defer delay={50} />
+		<Defer delay={10} />
+	</body>
+</html>

packages/astro/test/fixtures/solid-component/src/pages/nested.astro

@@ -0,0 +1,18 @@
+---
+import { AsyncComponent } from '../components/async-components.jsx';
+---
+
+<html>
+	<head><title>Nested Test</title></head>
+	<body>
+		<div>
+			<AsyncComponent client:load title="level-a">
+				<AsyncComponent client:load title="level-a-a" />
+				<AsyncComponent client:load title="level-a-b">
+					<AsyncComponent client:load title="level-a-b-a" />
+				</AsyncComponent>
+				<AsyncComponent client:load title="level-a-2" />
+			</AsyncComponent>
+		</div>
+	</body>
+</html>

packages/astro/test/fixtures/solid-component/src/pages/ssr-client-load-throwing.astro

@@ -0,0 +1,21 @@
+---
+import {
+	AsyncErrorInErrorBoundary,
+	SyncErrorInErrorBoundary,
+} from '../components/async-components.jsx';
+---
+
+<html>
+	<head><title>Solid</title></head>
+	<body>
+		<div>
+			<!-- 
+				Error boundary in hydrating component may generate scripts script:
+				https://github.com/ryansolid/dom-expressions/blob/6746f048c4adf4d4797276f074dd2d487654796a/packages/dom-expressions/src/server.js#L24
+				So make sure that the hydration script is generated on this page.
+			 -->
+			<AsyncErrorInErrorBoundary client:load />
+			<SyncErrorInErrorBoundary client:load />
+		</div>
+	</body>
+</html>

packages/astro/test/fixtures/solid-component/src/pages/ssr-client-load.astro

@@ -0,0 +1,17 @@
+---
+import { LazyCounter } from '../components/LazyCounter.jsx';
+import { AsyncComponent } from '../components/async-components.jsx';
+---
+
+<html>
+	<head><title>Solid</title></head>
+	<body>
+		<div>
+			<!-- client:load should generate exactly one hydration script per page -->
+			<AsyncComponent client:load />
+			<AsyncComponent client:load />
+			<!-- Lazy copmonents should render consistently, even on first render. -->
+			<LazyCounter client:load />
+		</div>
+	</body>
+</html>

packages/astro/test/fixtures/solid-component/src/pages/ssr-client-none-throwing.astro

@@ -0,0 +1,24 @@
+---
+import {
+	AsyncErrorInErrorBoundary,
+	SyncErrorInErrorBoundary,
+	// AsyncErrorComponent,
+	// SyncErrorComponent,
+} from '../components/async-components.jsx';
+---
+
+<html>
+	<head><title>Solid</title></head>
+	<body>
+		<div>
+			<!-- Async errors should be caught by ErrorBoundary -->
+			<AsyncErrorInErrorBoundary />
+			<!-- Sync errors should be caught by ErrorBoundary -->
+			<SyncErrorInErrorBoundary />
+
+			<!-- Error not wrapped in ErrorBoundary should bubble up to Astro renderToStaticMarkup() function. -->
+			<!-- <AsyncErrorComponent /> -->
+			<!-- <SyncErrorComponent /> -->
+		</div>
+	</body>
+</html>

packages/astro/test/fixtures/solid-component/src/pages/ssr-client-none.astro

@@ -0,0 +1,16 @@
+---
+import { AsyncComponent } from '../components/async-components.jsx';
+import { LazyCounter } from '../components/LazyCounter.jsx';
+---
+
+<html>
+	<head><title>Solid</title></head>
+	<body>
+		<div>
+			<!-- Static component should not create any hydration scripts -->
+			<AsyncComponent />
+			<!-- Lazy copmonents should render consistently, even on first render. -->
+			<LazyCounter />
+		</div>
+	</body>
+</html>

packages/astro/test/fixtures/solid-component/src/pages/ssr-client-only.astro

@@ -0,0 +1,13 @@
+---
+import { AsyncComponent } from '../components/async-components.jsx';
+---
+
+<html>
+	<head><title>Solid</title></head>
+	<body>
+		<div>
+			<!-- client only component should not generate hydration -->
+			<AsyncComponent client:only />
+		</div>
+	</body>
+</html>

packages/astro/test/solid-component.test.js

@@ -26,6 +26,106 @@ describe('Solid component', () => {
 			// test 2: Support rendering proxy components
 			expect($('#proxy-component').text()).to.be.equal('Hello world');
 		});
+
+		// ssr-client-none.astro
+		it('Supports server only components', async () => {
+			const html = await fixture.readFile('ssr-client-none/index.html');
+			const hydrationScriptCount = countHydrationScripts(html);
+			expect(hydrationScriptCount).to.be.equal(0);
+			const hydrationEventsCount = countHydrationEvents(html);
+			expect(hydrationEventsCount).to.be.equal(0);
+		});
+
+		it('Supports lazy server only components', async () => {
+			const html = await fixture.readFile('ssr-client-none/index.html');
+			const $ = cheerio.load(html);
+			// AsyncComponent renders 1 button
+			// LazyCounter renders 4 buttons
+			// Total is 5 buttons
+			expect($('button')).to.have.lengthOf(5);
+		});
+
+		// ssr-client-none-throwing.astro
+		it('Supports server only components with error boundaries', async () => {
+			const html = await fixture.readFile('ssr-client-none-throwing/index.html');
+			const hydrationScriptCount = countHydrationScripts(html);
+			expect(hydrationScriptCount).to.be.equal(0);
+			expect(html).to.include('Async error boundary fallback');
+			expect(html).to.include('Sync error boundary fallback');
+			const hydrationEventsCount = countHydrationEvents(html);
+			expect(hydrationEventsCount).to.be.equal(0);
+		});
+
+		// ssr-client-load.astro
+		it('Supports hydrating components', async () => {
+			const html = await fixture.readFile('ssr-client-load/index.html');
+			const hydrationScriptCount = countHydrationScripts(html);
+			expect(hydrationScriptCount).to.be.equal(1);
+		});
+
+		it('Supports lazy hydrating components', async () => {
+			const html = await fixture.readFile('ssr-client-load/index.html');
+			const $ = cheerio.load(html);
+			// AsyncComponent renders 1 button, and there are 2 AsyncComponents
+			// LazyCounter renders 4 buttons
+			// Total is 6 buttons
+			expect($('button')).to.have.lengthOf(6);
+		});
+
+		// ssr-client-load-throwing.astro
+		it('Supports hydrating components with error boundaries', async () => {
+			const html = await fixture.readFile('ssr-client-load-throwing/index.html');
+			const hydrationScriptCount = countHydrationScripts(html);
+			expect(hydrationScriptCount).to.be.equal(1);
+			expect(html).to.include('Async error boundary fallback');
+			expect(html).to.include('Sync error boundary fallback');
+			const hydrationEventsCount = countHydrationEvents(html);
+			expect(hydrationEventsCount).to.be.greaterThanOrEqual(1);
+		});
+
+		// ssr-client-only.astro
+		it('Supports client only components', async () => {
+			const html = await fixture.readFile('ssr-client-only/index.html');
+			const hydrationScriptCount = countHydrationScripts(html);
+			expect(hydrationScriptCount).to.be.equal(0);
+		});
+
+		// nested.astro
+
+		it('Injects hydration script before any SolidJS components in the HTML, even if heavily nested', async () => {
+			// TODO: This tests SSG mode, where the extraHead is generally available.
+			// Should add a test (and solution) for SSR mode, where head is more likely to have already
+			// been streamed to the client.
+			const html = await fixture.readFile('nested/index.html');
+
+			const firstHydrationScriptAt = getFirstHydrationScriptLocation(html);
+			expect(firstHydrationScriptAt).to.be.finite.and.greaterThan(0);
+
+			const firstHydrationEventAt = getFirstHydrationEventLocation(html);
+			expect(firstHydrationEventAt).to.be.finite.and.greaterThan(0);
+
+			expect(firstHydrationScriptAt).to.be.lessThan(
+				firstHydrationEventAt,
+				'Position of first hydration event'
+			);
+		});
+
+		it('Injects hydration script before any SolidJS components in the HTML, even if render order is reversed by delay', async () => {
+			const html = await fixture.readFile('deferred/index.html');
+
+			const firstHydrationScriptAt = getFirstHydrationScriptLocation(html);
+			expect(firstHydrationScriptAt).to.be.finite.and.greaterThan(0);
+
+			const firstHydrationEventAt = getFirstHydrationEventLocation(html);
+			expect(firstHydrationEventAt).to.be.finite.and.greaterThan(0);
+
+			const hydrationScriptCount = countHydrationScripts(html);
+			expect(hydrationScriptCount).to.be.equal(1);
+			expect(firstHydrationScriptAt).to.be.lessThan(
+				firstHydrationEventAt,
+				'Position of first hydration event'
+			);
+		});
 	});
 
 	if (isWindows) return;
@@ -64,3 +164,50 @@ describe('Solid component', () => {
 		});
 	});
 });
+
+/**
+ * Get a regex that matches hydration scripts.
+ *
+ * Based on this hydration script:
+ * https://github.com/ryansolid/dom-expressions/blob/main/packages/dom-expressions/assets/hydrationScripts.js
+ *
+ * Which is supposed to be injected in a page with hydrating Solid components
+ * essentially one time.
+ *
+ * We look for the hint "_$HY=".
+ *
+ * I chose to make this a function to avoid accidentally sharing regex state
+ * between tests.
+ *
+ * NOTE: These scripts have ocassionally changed in the past. If the tests
+ * start failing after a Solid version change, we may need to find a different
+ * way to count the hydration scripts.
+ */
+const createHydrationScriptRegex = (flags) => new RegExp(/_\$HY=/, flags);
+
+function countHydrationScripts(/** @type {string} */ html) {
+	return html.match(createHydrationScriptRegex('g'))?.length ?? 0;
+}
+
+function getFirstHydrationScriptLocation(/** @type {string} */ html) {
+	return html.match(createHydrationScriptRegex())?.index;
+}
+
+/**
+ * Get a regex that matches hydration events. A hydration event
+ * is when data is emitted to help hydrate a component during SSR process.
+ *
+ * We look for the hint "_$HY.r["
+ */
+const createHydrationEventRegex = (flags) => new RegExp(/_\$HY.r\[/, flags);
+
+function countHydrationEvents(/** @type {string} */ html) {
+	// Number of times a component was hydrated during rendering
+	// We look for the hint "_$HY.r["
+
+	return html.match(createHydrationEventRegex('g'))?.length ?? 0;
+}
+
+function getFirstHydrationEventLocation(/** @type {string} */ html) {
+	return html.match(createHydrationEventRegex())?.index;
+}

packages/integrations/solid/package.json

@@ -43,7 +43,7 @@
     "solid-js": "^1.8.5"
   },
   "peerDependencies": {
-    "solid-js": "^1.4.3"
+    "solid-js": "^1.8.5"
   },
   "engines": {
     "node": ">=18.14.1"

packages/integrations/solid/src/client.ts

@@ -1,14 +1,12 @@
+import { Suspense } from 'solid-js';
 import { createComponent, hydrate, render } from 'solid-js/web';
 
 export default (element: HTMLElement) =>
 	(Component: any, props: any, slotted: any, { client }: { client: string }) => {
-		// Prepare global object expected by Solid's hydration logic
-		if (!(window as any)._$HY) {
-			(window as any)._$HY = { events: [], completed: new WeakSet(), r: {} };
-		}
 		if (!element.hasAttribute('ssr')) return;
 
-		const boostrap = client === 'only' ? render : hydrate;
+		const isHydrate = client !== 'only';
+		const bootstrap = isHydrate ? hydrate : render;
 
 		let slot: HTMLElement | null;
 		let _slots: Record<string, any> = {};
@@ -35,13 +33,25 @@ export default (element: HTMLElement) =>
 		const { default: children, ...slots } = _slots;
 		const renderId = element.dataset.solidRenderId;
 
-		const dispose = boostrap(
-			() =>
-				createComponent(Component, {
-					...props,
-					...slots,
-					children,
-				}),
+		const dispose = bootstrap(
+			() => {
+				const inner = () =>
+					createComponent(Component, {
+						...props,
+						...slots,
+						children,
+					});
+
+				if (isHydrate) {
+					return createComponent(Suspense, {
+						get children() {
+							return inner();
+						},
+					});
+				} else {
+					return inner();
+				}
+			},
 			element,
 			{
 				renderId,

packages/integrations/solid/src/context.ts

@@ -11,7 +11,7 @@ export function getContext(result: RendererContext['result']): Context {
 	if (contexts.has(result)) {
 		return contexts.get(result)!;
 	}
-	let ctx = {
+	let ctx: Context = {
 		c: 0,
 		get id() {
 			return 's' + this.c.toString();

packages/integrations/solid/src/server.ts

@@ -1,53 +1,125 @@
-import { createComponent, renderToString, ssr } from 'solid-js/web';
+import {
+	createComponent,
+	generateHydrationScript,
+	NoHydration,
+	renderToString,
+	renderToStringAsync,
+	ssr,
+	Suspense,
+} from 'solid-js/web';
 import { getContext, incrementId } from './context.js';
 import type { RendererContext } from './types.js';
 
 const slotName = (str: string) => str.trim().replace(/[-_]([a-z])/g, (_, w) => w.toUpperCase());
 
-function check(this: RendererContext, Component: any, props: Record<string, any>, children: any) {
+type RenderStrategy = 'sync' | 'async';
+
+async function check(
+	this: RendererContext,
+	Component: any,
+	props: Record<string, any>,
+	children: any
+) {
 	if (typeof Component !== 'function') return false;
 	if (Component.name === 'QwikComponent') return false;
-	const { html } = renderToStaticMarkup.call(this, Component, props, children);
+
+	// There is nothing particularly special about Solid components. Basically they are just functions.
+	// In general, components from other frameworks (eg, MDX, React, etc.) tend to render as "undefined",
+	// so we take advantage of this trick to decide if this is a Solid component or not.
+
+	const { html } = await renderToStaticMarkup.call(this, Component, props, children, {
+		// The purpose of check() is just to validate that this is a Solid component and not
+		// React, etc. We should render in sync mode which should skip Suspense boundaries
+		// or loading resources like external API calls.
+		renderStrategy: 'sync' as RenderStrategy,
+	});
+
 	return typeof html === 'string';
 }
 
-function renderToStaticMarkup(
+// AsyncRendererComponentFn
+async function renderToStaticMarkup(
 	this: RendererContext,
 	Component: any,
 	props: Record<string, any>,
 	{ default: children, ...slotted }: any,
 	metadata?: undefined | Record<string, any>
 ) {
-	const renderId = metadata?.hydrate ? incrementId(getContext(this.result)) : '';
+	const ctx = getContext(this.result);
+	const renderId = metadata?.hydrate ? incrementId(ctx) : '';
 	const needsHydrate = metadata?.astroStaticSlot ? !!metadata.hydrate : true;
 	const tagName = needsHydrate ? 'astro-slot' : 'astro-static-slot';
 
-	const html = renderToString(
-		() => {
-			const slots: Record<string, any> = {};
-			for (const [key, value] of Object.entries(slotted)) {
-				const name = slotName(key);
-				slots[name] = ssr(`<${tagName} name="${name}">${value}</${tagName}>`);
-			}
-			// Note: create newProps to avoid mutating `props` before they are serialized
-			const newProps = {
-				...props,
-				...slots,
-				// In Solid SSR mode, `ssr` creates the expected structure for `children`.
-				children: children != null ? ssr(`<${tagName}>${children}</${tagName}>`) : children,
-			};
+	const renderStrategy = (metadata?.renderStrategy ?? 'async') as RenderStrategy;
 
-			return createComponent(Component, newProps);
-		},
-		{
-			renderId,
+	const renderFn = () => {
+		const slots: Record<string, any> = {};
+		for (const [key, value] of Object.entries(slotted)) {
+			const name = slotName(key);
+			slots[name] = ssr(`<${tagName} name="${name}">${value}</${tagName}>`);
 		}
-	);
+		// Note: create newProps to avoid mutating `props` before they are serialized
+		const newProps = {
+			...props,
+			...slots,
+			// In Solid SSR mode, `ssr` creates the expected structure for `children`.
+			children: children != null ? ssr(`<${tagName}>${children}</${tagName}>`) : children,
+		};
+
+		if (renderStrategy === 'sync') {
+			// Sync Render:
+			// <Component />
+			// This render mode is not exposed directly to the end user. It is only
+			// used in the check() function.
+			return createComponent(Component, newProps);
+		} else {
+			if (needsHydrate) {
+				// Hydrate + Async Render:
+				// <Suspense>
+				//   <Component />
+				// </Suspense>
+				return createComponent(Suspense, {
+					get children() {
+						return createComponent(Component, newProps);
+					},
+				});
+			} else {
+				// Static + Async Render
+				// <NoHydration>
+				//   <Suspense>
+				//     <Component />
+				// 	 </Suspense>
+				// </NoHydration>
+				return createComponent(NoHydration, {
+					get children() {
+						return createComponent(Suspense, {
+							get children() {
+								return createComponent(Component, newProps);
+							},
+						});
+					},
+				});
+			}
+		}
+	};
+
+	const componentHtml =
+		renderStrategy === 'async'
+			? await renderToStringAsync(renderFn, {
+					renderId,
+					// New setting since Solid 1.8.4 that fixes an errant hydration event appearing in
+					// server only components. Not available in TypeScript types yet.
+					// https://github.com/solidjs/solid/issues/1931
+					// https://github.com/ryansolid/dom-expressions/commit/e09e255ac725fd59195aa0f3918065d4bd974e6b
+					...({ noScripts: !needsHydrate } as any),
+			  })
+			: renderToString(renderFn, { renderId });
+
 	return {
 		attrs: {
 			'data-solid-render-id': renderId,
 		},
-		html,
+		html: componentHtml,
 	};
 }
 
@@ -55,4 +127,5 @@ export default {
 	check,
 	renderToStaticMarkup,
 	supportsAstroStaticSlot: true,
+	renderHydrationScript: () => generateHydrationScript(),
 };