Add support for SSR

[Fryuni]

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

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
starlight	✅ Ready (Inspect)	Visit Preview	May 12, 2024 0:57am

[changeset-bot]

🦋 Changeset detected

Latest commit: 0487488

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]

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

Here’s what will happen next:

1. 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!

2. In a few minutes, you’ll be able to see a preview of your changes on Vercel 🤩

3. 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]

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]

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]

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]

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]

waiting for this to be released 🙏

[mmv-dev]

@Fryuni. Thanks for your support. I have a tested this new changes and tried to deploy to Cloudflare. I was able to deploy it. But there is a catch, I have to get a Workers Paid subscription. Because in cloudflare there is limit for function file size (1 MiB), but the basic starlight function size is around 8-9 MiB (output = "server"). In Workers paid plan, the limit is 10 MiB. So i was able to deploy it. But for someone planning to implement this in a much bigger project which uses more server side capabilities, this might be something to look out for.

But once again, Thank you very much @Fryuni

[Fryuni]

but the basic starlight function size is around 8-9 MiB (output = "server"). In Workers paid plan, the limit is 10 MiB. So i was able to deploy it. But for someone planning to implement this in a much bigger project which uses more server side capabilities, this might be something to look out for.

Yeah, I don't think there is much for us to do on that front. In server output mode the entire content and all the tooling to render the content has to be shipped into a single function to be processed on each request, so that is a lot of data.

[marcelovicentegc]

Hey folks! Thanks for this effort @Fryuni. I just wanted to let you know that I shipped a website with your patched version from https://gitpkg.now.sh/Fryuni/starlight/packages/starlight?ssr-support to make Starlight work with https://authjs.dev/ (which requires SSR) and it worked seamlessly! I'm using Vercel's adapter.

I might reserve some time to take a look at the ins and outs of this PR and provide some assistance in getting it merged into the main branch.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	manual-setup.mdx	Source changed, localizations will be marked as outdated.
en	reference/configuration.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[Fryuni]

Hey @marcelovicentegc, thanks for the ping! There is not much blocking this PR; it is just a big change, and the team hasn't had the time to review it yet.

@delucis any chance this gets closer to the top of your to-do list? 🥺