refactor(adapter-reference): improve adapter API docs

[ArmandPhilippot]

Description (required)

• Adds some missing <Since />.
• Adds missing info for createExports(): a second argument exists to retrieve data from setAdapter().
• Adds docs for the missing astro/app APIs: app.getAllowedDomains(), app.removeBase(), app.setCookieHeaders()
• Fixes app.match() type: a second argument exists.
• Moves envGetSecret from "Adapter features" to "Astro features".
• Moves "Allow installation via astro add" to the end... not sure what is the best place for this.
• Replaces the types code block from Building an adapter with proper documentation.
• Rewords the "Server entrypoint" heading and turns it into h2.
• Replaces Exports > createExports() and Start > start() in "Build a server entrypoint" with some explanations about their shape.

See the relevant links to check types/default/since:

• experimentalStaticHeaders: added in feat(csp): add static header adapter function astro#13926
• AdapterSupport and AdapterSupportWithMessage: added in refactor: rework supportedAstroFeatures astro#11806
  • suppress in AdapterSupportWithMessage: added in Add option to suppress adapter feature support log astro#13842
• previewEntrypoint: added in Node.js standalone mode + support for astro preview astro#5056
• client: added in Allow adapters to customize headers for fetch requests astro#14543
• adapterFeatures: added in feat: adapter features, deprecate astro configs astro#7839
  • buildOutput: added in feat(hybrid): Clean logging and misc tweaks for hybrid removal astro#11942 (and feat: changesets for the hybrid removal astro#11941 for the changesets)
• supportedAstroFeatures: added in feat: astro features astro#7815
  • envGetSecret: added in feat(astro): experimental astro:env astro#10974
  • i18nDomains: added in feat(i18n): domain support astro#9143 (there was an i18n property before, but since this uses another name, this is "new")
  • sharpImageService: added in refactor: rework supportedAstroFeatures astro#11806
  • both envGetSecret and i18nDomains were added at the same time as the corresponding experimental feature, I'm not sure if we should use the stable release or not for them. Currently, I'm using the version of the experimental release.

astro/app public APIs (only the missing ones):

• getAdapterLogger: added in refactor: use new Astro internals astro#8254 but I can't find it in the changelog... looking at the merge data, this was 2 days before v3.0.0 so I think it's fine to use this version.
• getAllowedDomains: added in withastro/astro@6ee63bf which matches v5.14.2
• removeBase: add in Handle base in adapters astro#5290
• setCookieHeaders: added in Astro.cookies implementation astro#4876
• setManifestData: added in refactor: use SSR manifest in dev astro#7587

Room for improvement: except for envGetSecret that was already documented, the Astro features section is pretty succinct. I'm not sure how these features can/should be used, so I have not developed them.

Not documented

• app.setManifestData is publicly available when creating a new App (astro/app) but I couldn't find an usage in the source code so I wonder if this is a leftover that should be removed or something like that.

Related issues & labels (optional)

• Suggested label: add new content, consistency/formatting, improve or update documentation

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	af91d94
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6914a29f35bfc10008fb2966
😎 Deploy Preview	https://deploy-preview-12673--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.

[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.

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.

[florian-lefebvre]

This looks great! I always found our Adapter API docs a bit weak compared to the Integration API ones, love it!

[sarah11918]

I think everyone has done some amazing work supporting @ArmandPhilippot 's efforts! Only two points where I feel we really need to do a tiny bit better (called in both Matt and Florian to help), and once those feel good, this puppy LGTM!

[ArmandPhilippot]

Thanks everyone for the really helpful feedbacks! ❤️

I added a new astro/app/node section with the methods overridden by this module and the additional ones.

While doing so, I noticed we document the methods available from App once created (ie. const app = new App()), not the static methods. Should we? I noticed:

• App.getSetCookieFromResponse()
• App.validateForwardedHost()

We also have some static methods for NodeApp:

• NodeApp.createRequest()
• NodeApp.writeResponse()

I'm not quite sure how to make the distinction between the static methods and the others with the current structure.

Since info:

• nodeApp.render() signature has changed in Switch app.render signature astro#9199 so I set <Since /> to this release.
• nodeApp.headersMap and nodeApp.setHeadersMap(): added in feat(node): experimental static headers astro#13972

[sarah11918]

@florian-lefebvre Are you available to give feedback on Armand's latest commit and questions?

[florian-lefebvre]

I think we should document static methods as well, they are useful. It's fine to document these alongside the standard methods and just say they're static with a code example. For example usage of the node app specific static methods, I think this file is pretty good: https://github.com/withastro/astro/blob/5dbd59bdced080e3a9ae95ad91bbe737a2e3ba55/packages/integrations/node/src/serve-app.ts

[ArmandPhilippot]

Thanks, I just pushed a new commit to document them. Please check the accuracy because I'm not really sure how this can be used (e.g. I wrap validateForwardedHost in a start function to justify where allowedDomains comes from... but should this be used here?).

I added static method each time for people reading the example too quickly as additional clue.

And, if anyone want to check the versions:

• App.getSetCookieFromResponse(): added in Adapter enhancements astro#9661
• App.validateForwardedHost(): added in withastro/astro@6ee63bf which matches v5.14.2
• NodeApp.createRequest(): added in Adapter enhancements astro#9661
• NodeApp.writeResponse(): added in Adapter enhancements astro#9661

[florian-lefebvre]

New static methods were just added to address a CVE FYI withastro/astro#14743

[ArmandPhilippot]

Oh thanks! I wouldn't have thought to check the latest version... I'll add them to the docs tomorrow!

[sarah11918]

Great work, Armand! Just noting that when you're happy, I'm happy! (You can also request a Yan final boss review at any time!)

[ArmandPhilippot]

Thanks! And yeah, I'm glad we now have all those public APIs documented! But I must say, I didn't expected that when I started:

😅

And yes, a review from @yanthomasdev is always useful, if you have any spare time! 😄

Same for Florian or Matt, if you have time to check the accuracy of the new entries it would be helpful.
(No rush of course!)

[florian-lefebvre]

Looks pretty good! I think the the app methods could use more concrete examples perhaps (or maybe that'd belong to a guide, idk) but not blocking at all! This PR is big enough already, thanks a lot!

[yanthomasdev]

Good work, here's my final boss

[ArmandPhilippot]

I agree with Florian, some examples could probably be improved, but without building an adapter to determine what constitutes a useful minimal code snippet, it's a bit difficult (for me) to trim what is necessary or not in the current adapters. Showing too much/too specific code could also be confusing for users I think.

At least the docs are now a bit more detailed for those who wish to build their own adapter! So, this is NWTWWHB and we can always improve the code snippets later if/when we get feedbacks.

I think this looks ready to be merged! Thank you all again for your help!