feat: add experimental client prerender #9644

rossrobino · 2024-01-08T17:17:42Z

Changes

This adds an experimental progressive enhancement to enable the use of the Speculation Rules API to prerender pages (including running client-side JS) on the client. This feature is currently supported in Chrome and Edge without a flag. A feature that uniquely benefits multi-page application navigations.

I have limited experience with tree-shaking, but in my testing, it appears to be working if the feature is not enabled.

Testing

You can use the minimal example to test this feature with these modifications:

astro.config.mjs

import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({
+    prefetch: true,
+    experimental: {
+        clientPrerender: true,
+    },
});

index.astro

---

---

<html lang="en">
	<head>
		<meta charset="utf-8" />
		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
		<meta name="viewport" content="width=device-width" />
		<meta name="generator" content={Astro.generator} />
		<title>Astro</title>
	</head>
	<body>
		<h1>Astro</h1>
+.             <a href="/test" data-astro-prefetch>Prerender Test</a>
	</body>
</html>

Add new page: test.astro

---

---

<html lang="en">
    <head>
        <meta charset="utf-8" />
        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
        <meta name="viewport" content="width=device-width" />
        <meta name="generator" content={Astro.generator} />
        <title>Astro</title>
        <script>
            const layoutShift = () => {
                const h2 = document.querySelector("h2");
                h2.textContent = "Layout Shift"
            }

            layoutShift();

            const prerenderContent = () => {
                let text: string;
    
                //@ts-expect-error - `document.prerendering` is not supported in all browsers
                if (document.prerendering) {
                    text = "Prerendered on the client.";
                } else {
                    text = "Not prerendered.";
                }
                
                const preredered = document.createElement("p");
                preredered.textContent = text;
                document.body.appendChild(preredered);
            }

            prerenderContent();

        </script>
    </head>
    <body>
        <h1>Experimental Client Prerender</h1>
        <h2></h2>
        <p>The paragraph below and the h2 above are rendered by client side JavaScript. You can see the difference by navigating to this page from another, in comparison to refreshing the page.</p>
    </body>
</html>

Docs

/cc @withastro/maintainers-docs for feedback!

I have added jsdoc comments to my type, I'm not sure if any other docs will be needed since it is experimental.

changeset-bot · 2024-01-08T17:17:47Z

🦋 Changeset detected

Latest commit: d2ddd47

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

ematipico

Code-wise, this looks good to me.

We need:

a changeset https://github.com/withastro/astro/blob/main/CONTRIBUTING.md#making-a-pull-request. The changeset is a minor
new tests that you can add here: https://github.com/withastro/astro/blob/main/packages/astro/e2e/prefetch.test.js

sarah11918

Thank you for submitting this, @rossrobino ! I'm sure people will be excited to try this feature!

As Ema requested, a changeset is necessary here and the content should be of the form:

Adds an experimental feature flag clientPrerender to allow ...

I also made a suggestion to revise the docs so that they more matched the existing pattern/style. Please do make any factual corrections, and/or let me know if the nuance isn't quite right!

ALSO: I do suspect additional usage documentation might be necessary. For example, our existing Prefetch has several options, such as a default strategy and ways to opt-out on individual pages. I'll review your usage examples in the PR description more closely to decide what else might be needed. At the very least, there should be mention of whether this applies globally by default once enabled, how or whether one can opt out (or in) on an individual page/link basis etc.

So, I'll be back!

And... I'm back.

Here are my questions so far that I think people will have that should be answered in documentation:

why/when would someone choose to enable this flag? What does this change or unlock?
once the flag is enabled, what default behaviour changes (without doing anything else) if any? In other words, what is now different that people might need to check in their deployed project?
Is this a global, default change or does this provide a new opt-in, per link/page feature? If it's global, is it possible to opt out on a per link/page basis, and if so, how?
how does this relate to our existing Prefetch feature and its options? Does it have its own config options or strategies involved? (tap, hover, etc.) Does it inherit these values from the main prefetch config?

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

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

sarah11918 · 2024-01-13T15:21:23Z

Thanks so much, @rossrobino ! Great additions to the docs! I'll just do a little light editing of it, but I feel like we're providing much more helpful guidance and context for those who want to experiment with this feature!

rossrobino · 2024-01-13T20:02:18Z

Code-wise, this looks good to me.

We need:

a changeset https://github.com/withastro/astro/blob/main/CONTRIBUTING.md#making-a-pull-request. The changeset is a minor

new tests that you can add here: https://github.com/withastro/astro/blob/main/packages/astro/e2e/prefetch.test.js

@ematipico

I've added a changeset and tests, let me know if anything else is needed. Thanks!

sarah11918

OK, thanks again @rossrobino ! I had a chance to go through and make some suggestions for changeset/config docs.

Please review these and see what you think. Do feel free to make any changes if something is not right! This would be my suggested format based on how I think things are working, but if we need to correct, go ahead and do so!

.changeset/sixty-dogs-sneeze.md

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

rossrobino · 2024-01-15T14:13:36Z

@sarah11918 thank you for editing! I added them with a few modifications, let me know what you think.

ematipico

Looks good! @bluwy, could you give your review too, please?

bluwy

Some small nits below, but great work on the tests and implementation! Sorry for the long wait for the review, been stuck with other stuff.

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

packages/astro/src/prefetch/index.ts

bluwy · 2024-01-15T14:57:05Z

packages/astro/src/prefetch/index.ts

+	if (
+		clientPrerender &&
+		HTMLScriptElement.supports &&
+		HTMLScriptElement.supports('speculationrules')
+	) {
+		// this code is tree-shaken if unused
+		appendSpeculationRules(url);


Maybe in the future we can use prerender/prefetch when using with: 'link' or with: 'fetch' respectively. That way links that enter the viewport don't get prerendered entirely. But we can improve this later if needed.

sarah11918

OK, things are looking good! I think I'm only correcting commas and hyphens here. 😄

So, making this official call right now: no hyphens on any "pre" words! So, please be sure we've consistently got prefetch and prerender everywhere.

.changeset/sixty-dogs-sneeze.md

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

.changeset/sixty-dogs-sneeze.md

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

Co-authored-by: Bjorn Lu <bjornlu.dev@gmail.com>

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

sarah11918

I'm really happy with where these docs ended up! Thank you for your help @rossrobino ! 🥳

rossrobino · 2024-01-15T16:04:50Z

@sarah11918 great, thanks for all of your help!

feat: add experimental client prerender

eac2d01

github-actions bot added pkg: astro Related to the core `astro` package (scope) pr: docs A PR that includes documentation for review labels Jan 8, 2024

rossrobino added 2 commits January 8, 2024 13:14

Merge branch 'main' into feat-experimental-client-prerender

dab619d

Merge branch 'main' into feat-experimental-client-prerender

41beaf4

ematipico requested changes Jan 12, 2024

View reviewed changes

ematipico added this to the 4.2.0 milestone Jan 12, 2024

Merge branch 'main' into feat-experimental-client-prerender

905361c

sarah11918 reviewed Jan 12, 2024

View reviewed changes

packages/astro/src/@types/astro.ts Show resolved Hide resolved

packages/astro/src/@types/astro.ts Outdated Show resolved Hide resolved

rossrobino and others added 3 commits January 13, 2024 09:38

Merge branch 'main' into feat-experimental-client-prerender

aa5d0e2

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

fdfc861

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

docs: add more details about effects of the feature

66342fa

rossrobino added 2 commits January 13, 2024 10:23

add changeset

32f82b5

add tests

3ab937a

sarah11918 reviewed Jan 15, 2024

View reviewed changes

.changeset/sixty-dogs-sneeze.md Outdated Show resolved Hide resolved

packages/astro/src/@types/astro.ts Outdated Show resolved Hide resolved

edit jsdoc and changeset with suggestions

a6977a4

Merge branch 'main' into feat-experimental-client-prerender

c1d19e9

rossrobino requested review from ematipico and sarah11918 January 15, 2024 14:19

ematipico approved these changes Jan 15, 2024

View reviewed changes

ematipico requested a review from bluwy January 15, 2024 14:54

bluwy approved these changes Jan 15, 2024

View reviewed changes

sarah11918 reviewed Jan 15, 2024

View reviewed changes

sarah11918 mentioned this pull request Jan 15, 2024

Implement priority overrides for injected routes and redirects #9439

Merged

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

9b7bed4

Co-authored-by: Bjorn Lu <bjornlu.dev@gmail.com>

sarah11918 mentioned this pull request Jan 15, 2024

Document new routing priority behavior withastro/docs#6386

Merged

rossrobino and others added 6 commits January 15, 2024 10:45

Update packages/astro/src/prefetch/index.ts

d9069db

Co-authored-by: Bjorn Lu <bjornlu.dev@gmail.com>

Update .changeset/sixty-dogs-sneeze.md

182291c

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

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

1f32db2

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

Update .changeset/sixty-dogs-sneeze.md

53b2d78

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

Update .changeset/sixty-dogs-sneeze.md

d4d77bd

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

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

17b6aff

Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>

sarah11918 approved these changes Jan 15, 2024

View reviewed changes

Merge branch 'main' into feat-experimental-client-prerender

d2ddd47

ematipico merged commit a5f1682 into withastro:main Jan 17, 2024
13 of 14 checks passed

astrobot-houston mentioned this pull request Jan 17, 2024

[ci] release #9709

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add experimental client prerender #9644

feat: add experimental client prerender #9644

rossrobino commented Jan 8, 2024 •

edited by ematipico

Loading

changeset-bot bot commented Jan 8, 2024 •

edited

Loading

ematipico left a comment

sarah11918 left a comment •

edited

Loading

sarah11918 commented Jan 13, 2024

rossrobino commented Jan 13, 2024

sarah11918 left a comment

rossrobino commented Jan 15, 2024

ematipico left a comment

bluwy left a comment

bluwy Jan 15, 2024

sarah11918 left a comment

sarah11918 left a comment

rossrobino commented Jan 15, 2024

feat: add experimental client prerender #9644

feat: add experimental client prerender #9644

Conversation

rossrobino commented Jan 8, 2024 • edited by ematipico Loading

Changes

Testing

Docs

changeset-bot bot commented Jan 8, 2024 • edited Loading

🦋 Changeset detected

ematipico left a comment

Choose a reason for hiding this comment

sarah11918 left a comment • edited Loading

Choose a reason for hiding this comment

sarah11918 commented Jan 13, 2024

rossrobino commented Jan 13, 2024

sarah11918 left a comment

Choose a reason for hiding this comment

rossrobino commented Jan 15, 2024

ematipico left a comment

Choose a reason for hiding this comment

bluwy left a comment

Choose a reason for hiding this comment

bluwy Jan 15, 2024

Choose a reason for hiding this comment

sarah11918 left a comment

Choose a reason for hiding this comment

sarah11918 left a comment

Choose a reason for hiding this comment

rossrobino commented Jan 15, 2024

rossrobino commented Jan 8, 2024 •

edited by ematipico

Loading

changeset-bot bot commented Jan 8, 2024 •

edited

Loading

sarah11918 left a comment •

edited

Loading