feat: add experimental client prerender

.changeset/sixty-dogs-sneeze.md

@@ -0,0 +1,5 @@
+---
+"astro": minor
+---
+
+Adds an experimental option to prefetch to prerender pages on the client with the Speculation Rules API when supported.

packages/astro/e2e/prefetch.test.js

@@ -284,3 +284,106 @@ test.describe("Prefetch (prefetchAll: true, defaultStrategy: 'load')", () => {
 		expect(page.locator('link[rel="prefetch"][href$="/prefetch-load"]')).toBeDefined();
 	});
 });
+
+// Playwrights `request` event does not appear to fire when using the speculation rules API
+// Instead of checking for the added url, each test checks to see if `document.head`
+// contains a `script[type=speculationrules]` that has the `url` in it.
+test.describe('Prefetch (default), Experimental ({ clientPrerender: true })', () => {
+	/**
+	 * @param {import('@playwright/test').Page} page
+	 * @param {string} url
+	 * @returns the number of script[type=speculationrules] that have the url
+	 */
+	async function scriptIsInHead(page, url) {
+		return await page.evaluate((testUrl) => {
+			const scripts = document.head.querySelectorAll('script[type="speculationrules"]');
+			let count = 0;
+			for (const script of scripts) {
+				/** @type {{ prerender: { urls: string[] }[] }} */
+				const speculationRules = JSON.parse(script.textContent);
+				const specUrl = speculationRules.prerender.at(0).urls.at(0);
+				const indexOf = specUrl.indexOf(testUrl);
+				if (indexOf > -1) count++;
+			}
+			return count;
+		}, url);
+	}
+
+	let devServer;
+
+	test.beforeAll(async ({ astro }) => {
+		devServer = await astro.startDevServer({
+			experimental: {
+				clientPrerender: true,
+			},
+		});
+	});
+
+	test.afterAll(async () => {
+		await devServer.stop();
+	});
+
+	test('Link without data-astro-prefetch should not prefetch', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/'));
+		expect(await scriptIsInHead(page, '/prefetch-default')).toBeFalsy();
+	});
+
+	test('data-astro-prefetch="false" should not prefetch', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/'));
+		expect(await scriptIsInHead(page, '/prefetch-false')).toBeFalsy();
+	});
+
+	test('Link with search param should prefetch', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/'));
+		expect(await scriptIsInHead(page, '?search-param=true')).toBeFalsy();
+		await page.locator('#prefetch-search-param').hover();
+		await page.waitForFunction(
+			() => document.querySelectorAll('script[type=speculationrules]').length === 2
+		);
+		expect(await scriptIsInHead(page, '?search-param=true')).toBeTruthy();
+	});
+
+	test('data-astro-prefetch="tap" should prefetch on tap', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/'));
+		expect(await scriptIsInHead(page, '/prefetch-tap')).toBeFalsy();
+		await page.locator('#prefetch-tap').dragTo(page.locator('#prefetch-hover'));
+		expect(await scriptIsInHead(page, '/prefetch-tap')).toBeTruthy();
+	});
+
+	test('data-astro-prefetch="hover" should prefetch on hover', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/'));
+		expect(await scriptIsInHead(page, '/prefetch-hover')).toBeFalsy();
+		await page.locator('#prefetch-hover').hover();
+		await page.waitForFunction(
+			() => document.querySelectorAll('script[type=speculationrules]').length === 2
+		);
+		expect(await scriptIsInHead(page, '/prefetch-hover')).toBeTruthy();
+	});
+
+	test('data-astro-prefetch="viewport" should prefetch on viewport', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/'));
+		expect(await scriptIsInHead(page, '/prefetch-viewport')).toBeFalsy();
+		// Scroll down to show the element
+		await page.locator('#prefetch-viewport').scrollIntoViewIfNeeded();
+		await page.waitForFunction(
+			() => document.querySelectorAll('script[type=speculationrules]').length === 2
+		);
+		expect(await scriptIsInHead(page, '/prefetch-viewport')).toBeTruthy();
+	});
+
+	test('manual prefetch() works once', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/'));
+		expect(await scriptIsInHead(page, '/prefetch-manual')).toEqual(0);
+		await page.locator('#prefetch-manual').click();
+		expect(await scriptIsInHead(page, '/prefetch-manual')).toEqual(1);
+
+		// prefetch again should have no effect
+		await page.locator('#prefetch-manual').click();
+		expect(await scriptIsInHead(page, '/prefetch-manual')).toEqual(1);
+	});
+
+	test('data-astro-prefetch="load" should prefetch', async ({ page, astro }) => {
+		await page.goto(astro.resolveUrl('/'));
+		expect(await scriptIsInHead(page, 'prefetch-load')).toBeTruthy();
+	});
+});

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

@@ -1566,6 +1566,34 @@ export interface AstroUserConfig {
 		 * ```
 		 */
 		contentCollectionCache?: boolean;
+
+		/**
+		 * @docs
+		 * @name experimental.clientPrerender
+		 * @type {boolean}
+		 * @default `false`
+		 * @version: 4.2.0
+		 * @description
+		 * Enables pre-rendering a page on the client in supported browsers, including running client-side JavaScript.
+		 *
+		 * This feature uses the experimental [Speculation Rules Web API](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API).
+		 * You may wish to review the [possible risks when prerendering on the client](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API#unsafe_prefetching) before enabling this feature.
+		 *
+		 * Enable client side prerendering in your `astro.config`, no additional configuration is required.
+		 *
+		 * ```js
+		 * {
+		 * 	experimental: {
+		 * 		clientPrerender: true,
+		 * 	},
+		 * }
+		 * ```
+		 *
+		 * - This feature enhances the existing prefetch capability Astro provides. All client side JavaScript will be executed during the prerender to create a faster experience and reduce layout shift.
+		 * - Enabling this feature overrides the default prefetch behavior globally for all links that match your prefetch strategy. Instead of appending a `link` tag to the head of the document or fetching the page with JavaScript, a `script` tag will be appended with the corresponding speculation rules.
+		 * - Client side prerendering works based on browser support, if the Speculation Rules API is not supported, prefetch will fallback to the supported strategy.
+		 */
+		clientPrerender?: boolean;
 	};
 }
 

packages/astro/src/core/config/schema.ts

@@ -58,6 +58,7 @@ const ASTRO_CONFIG_DEFAULTS = {
 	experimental: {
 		optimizeHoistedScript: false,
 		contentCollectionCache: false,
+		clientPrerender: false,
 	},
 } satisfies AstroUserConfig & { server: { open: boolean } };
 
@@ -393,6 +394,10 @@ export const AstroConfigSchema = z.object({
 				.boolean()
 				.optional()
 				.default(ASTRO_CONFIG_DEFAULTS.experimental.contentCollectionCache),
+			clientPrerender: z
+				.boolean()
+				.optional()
+				.default(ASTRO_CONFIG_DEFAULTS.experimental.clientPrerender),
 		})
 		.strict(
 			`Invalid or outdated experimental feature.\nCheck for incorrect spelling or outdated Astro version.\nSee https://docs.astro.build/en/reference/configuration-reference/#experimental-flags for a list of all current experiments.`

packages/astro/src/prefetch/index.ts

@@ -16,6 +16,8 @@ const listenedAnchors = new WeakSet<HTMLAnchorElement>();
 let prefetchAll: boolean = __PREFETCH_PREFETCH_ALL__;
 // @ts-expect-error injected global
 let defaultStrategy: string = __PREFETCH_DEFAULT_STRATEGY__;
+// @ts-expect-error injected global
+let clientPrerender: boolean = __EXPERIMENTAL_CLIENT_PRERENDER__;
 
 interface InitOptions {
 	defaultStrategy?: string;
@@ -216,7 +218,14 @@ export function prefetch(url: string, opts?: PrefetchOptions) {
 	const priority = opts?.with ?? 'link';
 	debug?.(`[astro] Prefetching ${url} with ${priority}`);
 
-	if (priority === 'link') {
+	if (
+		clientPrerender &&
+		HTMLScriptElement.supports &&
+		HTMLScriptElement.supports('speculationrules')
+	) {
+		// this code is tree-shaken if unused
+		appendSpeculationRules(url);
+	} else if (priority === 'link') {
 		const link = document.createElement('link');
 		link.rel = 'prefetch';
 		link.setAttribute('href', url);
@@ -301,3 +310,26 @@ function onPageLoad(cb: () => void) {
 		cb();
 	});
 }
+
+/**
+ * Appends a `<script type="speculationRules">` tag to the head of the
+ * document that prerenders the `url` passed in.
+ *
+ * Modifying the script and appending a new link does not trigger the prerender.
+ * A new script must be added for each `url`.
+ *
+ * @param url The url of the page to prerender.
+ */
+function appendSpeculationRules(url: string) {
+	const script = document.createElement('script');
+	script.type = 'speculationrules';
+	script.textContent = JSON.stringify({
+		prerender: [
+			{
+				source: 'list',
+				urls: [url],
+			},
+		],
+	});
+	document.head.append(script);
+}

packages/astro/src/prefetch/vite-plugin-prefetch.ts

@@ -49,7 +49,11 @@ export default function astroPrefetch({ settings }: { settings: AstroSettings })
 			if (id.includes(prefetchInternalModuleFsSubpath)) {
 				return code
 					.replace('__PREFETCH_PREFETCH_ALL__', JSON.stringify(prefetch?.prefetchAll))
-					.replace('__PREFETCH_DEFAULT_STRATEGY__', JSON.stringify(prefetch?.defaultStrategy));
+					.replace('__PREFETCH_DEFAULT_STRATEGY__', JSON.stringify(prefetch?.defaultStrategy))
+					.replace(
+						'__EXPERIMENTAL_CLIENT_PRERENDER__',
+						JSON.stringify(settings.config.experimental.clientPrerender)
+					);
 			}
 		},
 	};