Add support for SSR #1255

Fryuni · 2023-12-08T15:34:38Z

Summary

Add configuration for not prerendering Starlight pages.

This enables using components with SSR logic on Starlight pages, whether in the content or as component overrides.

Notes

Double index

To do this without triggering multiple warnings, there are now two .astro pages for the index entrypoint:

The pre-existing index.astro is always prerendered and uses getStaticPaths and Astro.props to receive information about the route.
A new indexSSR.astro that is never prerendered and retrieves the information about the route from the dynamic route parameter.

Route parameter indexing

To make the SSR rendering efficient, a lookup map for all the content was created using the parameter that will be received from the dynamic route.

Pagefind

Pagefind indexing requires access to the HTML file generated by the routes, but those are not available when building for SSR, so Pagefind is not supported when using SSR.

The solution that I implemented for this is that when both SSR and Pagefind are enabled for Starlight, the content of the docs is pre-rendered for indexing but not included in the final build. The final content served will be from SSR, but the index will be built from that static rendering.

Default behavior

Starlight will default to the same as any other Astro page, prerendering when the output mode is not defined, when it is static, and when it is hybrid. When the output mode is server, Starlight will default to SSR.

~~Starlight previously didn't build at all when the site had output mode set to server, so the different default is not, AFAICT, a breaking change.~~

Starlight will default to prerender pages, which differs from the default for Astro pages. This is to maintain compatibility and because docs pages are most commonly not dynamic. Users must set prerender: false in their Starlight configuration to enable on-demand docs page rendering. At the moment, this applies to all Starlight pages. Future work could be done to support SSR on only some of the pages.

TODO

Disable Pagefind by default and make it incompatible
Move all child_process logic to build plugins (git information)
Add tests for SSR builds

changeset-bot · 2023-12-08T15:34:43Z

🦋 Changeset detected

Latest commit: fac8782

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

This PR includes changesets to release 1 package

Name	Type
@astrojs/starlight	Minor

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

astrobot-houston · 2023-12-08T15:35:06Z

Hello! Thank you for opening your first PR to Starlight! ✨

Here’s what will happen next:

Our GitHub bots will run to check your changes.
If they spot any issues you will see some error messages on this PR.
Don’t hesitate to ask any questions if you’re not sure what these mean!
In a few minutes, you’ll be able to see a preview of your changes on Vercel 🤩
One or more of our maintainers will take a look and may ask you to make changes.
We try to be responsive, but don’t worry if this takes a few days.

Fryuni · 2023-12-10T02:56:38Z

For anyone that want to try this out on their website to check for problems you can install it with:

npm install https://gitpkg.now.sh/Fryuni/starlight/packages/starlight?ssr-support

yarn add https://gitpkg.now.sh/Fryuni/starlight/packages/starlight?ssr-support

pnpm add https://gitpkg.now.sh/Fryuni/starlight/packages/starlight?ssr-support

Fryuni · 2023-12-10T13:15:19Z

Probably blocked by withastro/astro#9392, due to that bug any project using Starlight with SSR cannot add any other page to the project as everything will be overridden by Starlight's [...slug] route.

patryk-smc · 2024-01-24T16:13:54Z

Any updates on that? I have to patch package to add export const prerender = true; to the index.astro to make it work with @astrojs/vercel/serverless

Fryuni · 2024-01-24T17:17:34Z

This depended on withastro/astro#9439, released on 4.2. It's on my pipe to come back to this and make any necessary changes. I'll probably ping people to review it by next Tuesday.

ronildo · 2024-01-30T15:36:39Z

waiting for this to be released 🙏

delucis

Thanks for taking my suggestions on board @Fryuni! This is in great shape. Left a last couple of comments on the files I didn’t get to yesterday.

packages/starlight/package.json

delucis · 2024-08-31T21:47:21Z

packages/starlight/utils/plugins.ts

@@ -72,6 +73,13 @@ export async function runPlugins(
 		});
 	}

+	if (context.config.output === 'static' && !starlightConfig.prerender) {


I guess we’ll need to revisit this for Astro v5 given withastro/astro#11824 — probably something like checking there’s an adapter? (No action needed, just sharing the observation to up our chances of one of us remembering 😁)

This PR is almost the entirety of v4. It started two days after 4.0.0 and now we have to consider how v5 just around the corner will break it 😅

packages/starlight/utils/plugins.ts

packages/starlight/utils/routing.ts

packages/starlight/utils/user-config.ts

[skip ci] Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

delucis

Thanks for the last updates @Fryuni! Looks good to me! 🎊

I think one thing we can think about for the future is if this needs any more documentation (the current SSR section is a bit hidden in the manual setup guide), but I’m happy to run with this as it’s a rarer option for people.

Will take a look to see if there are other things we’d like to get released with this and decide when to cut the next minor.

delucis · 2024-09-06T16:07:32Z

Updated the end-to-end fixtures to the latest Astro release to match the updates in #2287 — tests still all seem good!

@HiDeoo

I think @HiDeoo is happy now too!

sarah11918 · 2024-09-06T22:36:06Z

Just wanted to say I'm excited! 🥳 Congrats, @Fryuni !

marcelovicentegc · 2024-09-06T22:40:54Z

Hey, folks! I just wanted to let you know that I've been following this PR for the last couple of months and wanted to congrats everyone involved on this effort. You did an amazing job here @Fryuni @HiDeoo and @delucis! I'm saving this PR as an example of open source contribution.

Really cool to see these in-depth discussions happening async, and moving forward!

Again, congrats and thank you @Fryuni !

rodolphoasb · 2024-09-06T22:43:14Z

Trabalho incrível, @Fryuni! Congrats team!

OliverSpeir · 2024-09-06T22:45:19Z

🎉

* main: (37 commits) [ci] format i18n(ko-KR): update `manual-setup.mdx` (withastro#2294) i18n(ko-KR): update `configuration.mdx` (withastro#2295) [ci] release (withastro#2292) Add support for SSR (withastro#1255) Add Markdoc preset and example (withastro#2249) Refactor sidebar persistence logic for better slow device performance (withastro#2242) [ci] format Add docs.ryzekit.com to showcase (withastro#2291) Update astro dependency to 4.15.3 across monorepo (withastro#2289) [ci] release (withastro#2290) Prevent Zod errors from crashing build (withastro#2288) i18n(fr): update `guides/css-and-tailwind` (withastro#2286) i18n(ko-KR): update `css-and-tailwind.mdx` (withastro#2284) Add WCAG AAA colour contrast option to theme editor (withastro#2282) [ci] release (withastro#2283) Parse `<StarlightPage />` frontmatter asynchronously (withastro#2279) Ensure unhandled directives are restored without any extra whitespace (withastro#2281) i18n(fr): update `resources/plugins` (withastro#2278) i18n(ko-KR): update `plugins.mdx` (withastro#2277) ...

* main: (22 commits) i18n(ru): update `ru/manual-setup.mdx` and `ru/reference/configuration.mdx` (withastro#2307) [ci] format i18n(ru): update some guides (withastro#2306) i18n(fr): update `manual-setup` (withastro#2299) i18n(fr): update `guides/pages` (withastro#2298) [ci] release (withastro#2304) Convert URL to file path correctly for Git virtual module (withastro#2303) i18n(fr): update `reference/configuration` (withastro#2296) i18n(fr): update `guides/authoring-content` (withastro#2297) Update `yummacss.com.png` thumbnail (withastro#2301) i18n(ko-KR): update `pages.mdx` (withastro#2293) [ci] format i18n(ko-KR): update `authoring-content.mdx` (withastro#2300) [ci] format i18n(ko-KR): update `manual-setup.mdx` (withastro#2294) i18n(ko-KR): update `configuration.mdx` (withastro#2295) [ci] release (withastro#2292) Add support for SSR (withastro#1255) Add Markdoc preset and example (withastro#2249) Refactor sidebar persistence logic for better slow device performance (withastro#2242) ...

Fryuni added 2 commits December 8, 2023 12:28

Add suport for SSR

1a288b9

Handle route not found

b55f0e7

This comment was marked as outdated.

Sign in to view

github-actions bot added the 🌟 core Changes to Starlight’s main package label Dec 8, 2023

vercel bot deployed to Preview December 8, 2023 15:36 View deployment

Fryuni added 4 commits December 8, 2023 17:10

Fix SSR page typos

45d9e41

Specify prerendering option for injected routes

6762da6

Add an SSR example

867ba4f

Make pagefind work with SSR

9edf662

vercel bot deployed to Preview December 8, 2023 21:34 View deployment

Fryuni marked this pull request as draft December 8, 2023 22:04

Pre-render for pagefind

b66c763

vercel bot deployed to Preview December 10, 2023 02:17 View deployment

Fryuni added 2 commits December 9, 2023 23:23

Add changeset

c2df2fe

Merge branch 'main' into ssr-support

62ceb4a

Fryuni marked this pull request as ready for review December 10, 2023 02:23

vercel bot deployed to Preview December 10, 2023 02:25 View deployment

Fryuni changed the title ~~Add suport for SSR~~ Add support for SSR Dec 10, 2023

Merge branch 'main' into ssr-support

fda9681

vercel bot deployed to Preview December 14, 2023 15:46 View deployment

delucis mentioned this pull request Jan 4, 2024

Can't deploy on Cloudflare #1333

Closed

1 task

Fryuni added 2 commits January 30, 2024 17:37

Merge branch 'main' into ssr-support

29694b3

Add SSR demonstration to example

670f4e8

Fryuni and others added 4 commits August 30, 2024 22:03

Update threshold

9ca0612

Add a comment about the seemingly unnecessary gitignore file

194e9e8

Merge remote-tracking branch 'upstream/main' into ssr-support

40be30b

pnpm format

d754d9b

delucis reviewed Aug 31, 2024

View reviewed changes

delucis mentioned this pull request Aug 31, 2024

Merge output: hybrid and output: static withastro/astro#11824

Merged

Fryuni and others added 2 commits August 31, 2024 19:53

Apply suggestions from code review

c905fef

[skip ci] Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

Change linkedom to dev dep

1ad3cd8

delucis approved these changes Sep 2, 2024

View reviewed changes

delucis added 2 commits September 2, 2024 19:10

Merge branch 'main' into ssr-support

e75ea3c

Update vitest.config.ts thresholds

fb647b6

HiDeoo mentioned this pull request Sep 6, 2024

Update astro dependency to 4.15.3 across monorepo #2289

Merged

delucis added 3 commits September 6, 2024 17:37

Merge branch 'main' into pr/1255

3b6940d

Update Astro in new fixtures

636abe5

Fix type compatibility in vitePluginStarlightUserConfig()

2dc5d7b

Merge branch 'main' into pr/1255

fac8782

Fryuni merged commit 6f3202b into withastro:main Sep 6, 2024
16 checks passed

Fryuni deleted the ssr-support branch September 6, 2024 22:38

This was referenced Sep 7, 2024

i18n(ko-KR): update manual-setup.mdx #2294

Merged

i18n(ko-KR): update configuration.mdx #2295

Merged

This was referenced Sep 7, 2024

i18n(fr): update reference/configuration #2296

Merged

i18n(fr): update manual-setup #2299

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for SSR #1255

Add support for SSR #1255

Fryuni commented Dec 8, 2023 •

edited

Loading

This comment was marked as outdated.

changeset-bot bot commented Dec 8, 2023 •

edited

Loading

astrobot-houston commented Dec 8, 2023

Fryuni commented Dec 10, 2023

Fryuni commented Dec 10, 2023

patryk-smc commented Jan 24, 2024

Fryuni commented Jan 24, 2024

ronildo commented Jan 30, 2024

delucis left a comment

delucis Aug 31, 2024

Fryuni Aug 31, 2024

delucis left a comment •

edited

Loading

delucis commented Sep 6, 2024

sarah11918 commented Sep 6, 2024

marcelovicentegc commented Sep 6, 2024

rodolphoasb commented Sep 6, 2024

OliverSpeir commented Sep 6, 2024

Add support for SSR #1255

Add support for SSR #1255

Conversation

Fryuni commented Dec 8, 2023 • edited Loading

Summary

Notes

Double index

Route parameter indexing

Pagefind

Default behavior

TODO

This comment was marked as outdated.

changeset-bot bot commented Dec 8, 2023 • edited Loading

🦋 Changeset detected

astrobot-houston commented Dec 8, 2023

Fryuni commented Dec 10, 2023

Fryuni commented Dec 10, 2023

patryk-smc commented Jan 24, 2024

Fryuni commented Jan 24, 2024

ronildo commented Jan 30, 2024

delucis left a comment

Choose a reason for hiding this comment

delucis Aug 31, 2024

Choose a reason for hiding this comment

Fryuni Aug 31, 2024

Choose a reason for hiding this comment

delucis left a comment • edited Loading

Choose a reason for hiding this comment

delucis commented Sep 6, 2024

sarah11918 commented Sep 6, 2024

marcelovicentegc commented Sep 6, 2024

rodolphoasb commented Sep 6, 2024

OliverSpeir commented Sep 6, 2024

Fryuni commented Dec 8, 2023 •

edited

Loading

changeset-bot bot commented Dec 8, 2023 •

edited

Loading

delucis left a comment •

edited

Loading