Document custom prerenderers

[matthewp]

Description (required)

Custom prerenderers handle prerendering (aka static generation) during the build. The API primarily exists so that non-Node runtimes can run the prerender build in their own runtimes to generate page and therefore have access to that runtime specific APIs (such as the Deno global in Deno).

This adds documentation to the integration and adapter reference pages.

For Astro version: 6.x. See astro PR #15077.

[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

File	Note
en/reference/adapter-reference.mdx	Source changed, localizations will be marked as outdated.
en/reference/integrations-reference.mdx	Source changed, localizations will be marked as outdated.
en/reference/modules/astro-static-paths.mdx	Localization added, will be marked as complete.

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.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	a43ce74
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6978c8c58aa54a00087dc438
😎 Deploy Preview	https://deploy-preview-13143--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[sarah11918]

All the writing looks great here Matthew! I'm going to call @ArmandPhilippot in here to help organize!

We have separate individual pages for every module (e.g. astro:assets, astro:content) to organize the API references, so I think this means we should have a new astro:static-paths page now, too. We might also want to document AstroPrerenderer with our formal API type.

[ArmandPhilippot]

Yes, I agree:

• we should have a new AstroPrerenderer section under Integration types reference.
• we could have another section for PathWithRoute in the same place, with a link targeting it in the getStaticPaths() property (instead of saying { pathname: string, route: RouteData } objects)
• we should add a link from the "setPrerenderer() option" section to the new AstroPrerenderer section
• then in "Custom prerenderer", on the Adapter API page, we don't need to describe AstroPrerenderer, we can just link to the right section
• and, yes, astro:static-paths should probably be moved to a new page in https://github.com/withastro/docs/tree/main/src/content/docs/en/reference/modules

I can help with the reorganization if you want, but I'll probably need your help to check/complete/make accurate the descriptions for the added sections!

[sarah11918]

@ArmandPhilippot Happy if you'd like to take the lead sketching things out, and Matthew and I can help filling out the content as needed!

[matthewp]

@ArmandPhilippot Sounds good, the only thing I would maybe push back on is PathWithRoute, that type is incidental and I wouldn't want to lock us in to exposing that type or its exact shape. Instead what we should be locked into is the return type of getStaticPaths which is why I specified the shape rather than the name, if that makes sense.

[ArmandPhilippot]

@matthewp Yep, that makes sense! I'll try to find a better way to express that without the link, because I'm not sure this is the most readable way at the moment. Thanks for the feedback! Not sure if I'll be able to do that tonight (CET), but at worst I'll do that tomorrow!

[ArmandPhilippot]

I think the reorganization is done. Feel free to check the accuracy of the new sections! For example, here looking at the JSDoc, I wasn't sure if this was referring to the getStaticPaths() I linked or the one available in AstroPrerenderer.

[matthewp]

Yep, great explanation!

[sarah11918]

@ArmandPhilippot This organization and these entries all look overall great to me!

There are a couple of tiny spots I might fix, but first I'll let @matthewp read and make any suggestions so that I just polish over top of that.

Thank you so much! This is amazing work 🙌

[sarah11918]

Noting here that I'll wait for @matthewp to approve Armand's additions first, but I did notice that I don't think we link to the new virtual module page anywhere from the Adapter API nor Integrations API pages? So, there probably is some good opportunity for linkage here!

[matthewp]

wow, this is all fantastic

[matthewp]

til

[matthewp]

I think everything looks great, thanks for tackling this @ArmandPhilippot !

[yanthomasdev]

Great work here. LGTM

[sarah11918]

I think all these docs look great! I'm left wondering where (if anywhere?) it makes sense to link to the new page/StaticPaths.

Of all the docs here, we don't have a usage example on a different page showing importing and using StaticPaths from the new virtual module (which would be an obvious place we'd have occasion to link out to its reference entry).

Does this mean we should maybe update some text on the Adapter API page (#building-a-server-entrypoint, or #createExports?) that briefly mentions and links out to its use case?

Non-blocking, but having a reference page that nothing links to means that we're not helping people find this as a solution to a thing they might be trying to do! They don't often go to an API reference unless they already know what they're looking up!

[ArmandPhilippot]

Based on the discussion with Florian in #13229, the best place for a link could be either "Building an adapter" or the new "Custom prerenderer" section.

It seems "Building a server entrypoint" and createExports() only concerns those building an adapter with legacy-dynamic. Maybe astro:static-paths is also useful with entryType: "self"? And maybe this is only useful with self?
If so, the module page should use something else than createExport() (I used that to get the manifest from somewhere). In the changeset I see Matthew uses an exported createApp() function...

I don't know what is the best use case... that's probably why I forgot that link. 😅 We might need Matthew's opinion on this!

[sarah11918]

I think in general it's just, "What will someone want to do when they need to know this?" And if it's "build an adapter" then yes, something that helps guide people to building an adapter that needs this would be helpful?

It's also not strictly speaking a blocker here! Just something to bring up as a bit of a smell, and something that could be addressed in a later PR, if necessary.