Skip to content

Add support for SSR#1255

Merged
Fryuni merged 127 commits intowithastro:mainfrom
Fryuni:ssr-support
Sep 6, 2024
Merged

Add support for SSR#1255
Fryuni merged 127 commits intowithastro:mainfrom
Fryuni:ssr-support

Conversation

@Fryuni
Copy link
Copy Markdown
Member

@Fryuni Fryuni commented Dec 8, 2023 •
edited
Loading

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

This comment was marked as outdated.

Sign in to view
@changeset-bot
Copy link
Copy Markdown

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

🦋 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

@github-actions github-actions bot added the 🌟 core Changes to Starlight’s main package label Dec 8, 2023
@astrobot-houston
Copy link
Copy Markdown
Contributor

astrobot-houston commented Dec 8, 2023

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 Fryuni marked this pull request as draft December 8, 2023 22:04
@Fryuni Fryuni marked this pull request as ready for review December 10, 2023 02:23
@Fryuni Fryuni changed the title Add suport for SSR Add support for SSR Dec 10, 2023
@Fryuni
Copy link
Copy Markdown
Member Author

Fryuni commented Dec 10, 2023

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
Copy link
Copy Markdown
Member Author

Fryuni commented Dec 10, 2023

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.

@delucis delucis mentioned this pull request Jan 4, 2024
Closed
1 task
@patjakubik
Copy link
Copy Markdown
Contributor

patjakubik commented Jan 24, 2024

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
Copy link
Copy Markdown
Member Author

Fryuni commented Jan 24, 2024

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
Copy link
Copy Markdown
Contributor

ronildo commented Jan 30, 2024

waiting for this to be released 🙏

delucis
delucis reviewed Aug 31, 2024
View reviewed changes
Copy link
Copy Markdown
Member

@delucis delucis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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/utils/plugins.ts
});
}

if (context.config.output === 'static' && !starlightConfig.prerender) {
Copy link
Copy Markdown
Member

@delucis delucis Aug 31, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 😁)

Copy link
Copy Markdown
Member Author

@Fryuni Fryuni Aug 31, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 😅

@delucis delucis mentioned this pull request Aug 31, 2024
Merged
Fryuni and others added 2 commits August 31, 2024 19:53
@Fryuni @delucis
Apply suggestions from code review
c905fef 
[skip ci]

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
@Fryuni
Change linkedom to dev dep
1ad3cd8
delucis
delucis approved these changes Sep 2, 2024
View reviewed changes
Copy link
Copy Markdown
Member

@delucis delucis left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@HiDeoo HiDeoo mentioned this pull request Sep 6, 2024
Merged
@delucis
Copy link
Copy Markdown
Member

delucis commented Sep 6, 2024

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

@delucis delucis dismissed HiDeoo’s stale review September 6, 2024 16:47

I think @HiDeoo is happy now too!

@sarah11918
Copy link
Copy Markdown
Member

sarah11918 commented Sep 6, 2024

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

@Fryuni Fryuni merged commit 6f3202b into withastro:main Sep 6, 2024
@marcelovicentegc
Copy link
Copy Markdown
Contributor

marcelovicentegc commented Sep 6, 2024

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
Copy link
Copy Markdown

rodolphoasb commented Sep 6, 2024

Trabalho incrível, @Fryuni! Congrats team!

@OliverSpeir
Copy link
Copy Markdown
Contributor

OliverSpeir commented Sep 6, 2024

🎉

This was referenced Sep 7, 2024
Merged
Merged
This was referenced Sep 7, 2024
Merged
Merged
@Nin3lee Nin3lee mentioned this pull request Sep 25, 2024
Merged
@Sujit-AI-Sec Sujit-AI-Sec mentioned this pull request Oct 27, 2024
Open
This was referenced Oct 28, 2024
Merged
Merged
@ajile-in ajile-in mentioned this pull request Nov 4, 2024
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@delucis delucis delucis approved these changes

@HiDeoo HiDeoo Awaiting requested review from HiDeoo

Assignees

No one assigned

Labels

🌟 core Changes to Starlight’s main package 📚 docs Documentation website changes 🌟 minor Change that triggers a minor release

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.