refactor(adapter-reference): improve adapter API docs #12673

ArmandPhilippot · 2025-11-05T14:48:30Z

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 · 2025-11-05T14:48:35Z

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`17f719a`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/690e1e06e78fa400089fa108
😎 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 · 2025-11-05T14:49:38Z

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.

src/content/docs/en/reference/adapter-reference.mdx

ascorbic · 2025-11-07T10:42:30Z

src/content/docs/en/reference/adapter-reference.mdx


-export function createExports(manifest) {
-  const app = new App(manifest);
+When this feature is enabled, Astro will return a map of the `Headers` emitted by the static pages. This map `experimentalRouteToHeaders` is available in the [`astro:build:generated` hook](/en/reference/integrations-reference/#astrobuildgenerated).


Suggested change

When this feature is enabled, Astro will return a map of the `Headers` emitted by the static pages. This map `experimentalRouteToHeaders` is available in the [`astro:build:generated` hook](/en/reference/integrations-reference/#astrobuildgenerated).

Defines if the adapter supports setting response headers for static pages. When this feature is enabled, Astro will return a map of the `Headers` emitted by the static pages. This map `experimentalRouteToHeaders` is available in the [`astro:build:generated` hook](/en/reference/integrations-reference/#astrobuildgenerated). The adapter could then use this to generate a `_headers` or other configuration file, for example.

I'm not sure about the wording, but it would be good to specify what this is for, not just what it does.

Maybe something like this?

Suggested change

When this feature is enabled, Astro will return a map of the `Headers` emitted by the static pages. This map `experimentalRouteToHeaders` is available in the [`astro:build:generated` hook](/en/reference/integrations-reference/#astrobuildgenerated).

Whether or not the adapter provides experimental support for setting response headers for static pages. When this feature is enabled, Astro will return a map of the `Headers` emitted by the static pages. This map `experimentalRouteToHeaders` is available in the [`astro:build:generated` hook](/en/reference/integrations-reference/#astrobuildgenerated) for generating files such as a `_headers` that allows you to make changes to the default HTTP header.

I like Sarah's version but I'm not quite sure what _headers is. Reading Matt's suggestion I guess this is a configuration file so maybe we need to say it explicitly ("a _headers configuration file") to avoid confusion?

That's why I said "generating files such as a _headers. Apparently, in some cases it's a .txt file, but e.g. saw for Cloudflare that someone needed to remove the file extension. What if we just remove the "a"?

"for generating files such as _headers ..."

I followed the trail to get from https://docs.netlify.com/manage/routing/headers/ to https://developer.mozilla.org/en-US/docs/Glossary/HTTP_header and even had a draft that included the purpose of the HTTP header file, but ultimately, it's not our job to go that far and document that basic, I think, for someone reading the Adapter API?

Oh, I thought I had already answered, I probably forgot to click the button. 😅

Thanks for the extra context, I wasn't aware this was an "expected" file. So yes, this sounds good to me! (I think I prefer without a before, but I'm not a native speaker so choose the version that sounds the more correct to you!)

Yeah, my wording was unclear! There was an implied [file] after "_headers". So to be explicit, it would be

The adapter could then use this to generate a `_headers` file or other configuration file.

So, not "a (_headers) or (other configuration file)", but "a (_headers or other configuration) file"!

Co-authored-by: Matt Kane <[email protected]>

src/content/docs/en/reference/adapter-reference.mdx

florian-lefebvre

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

florian-lefebvre · 2025-11-07T12:32:57Z

src/content/docs/en/reference/adapter-reference.mdx

 ```

-#### Start
+The second argument passed to `createExports()` can be useful when you need to access build-time configuration in your server entrypoint. For example, your server entrypoint might need the directory path in the build output where the resources generated by Astro are located:


Maybe link back to the args section?

Sure, good idea. I'm not sure how to integrate it in the current version, so maybe (while reusing Sarah's suggestion from the other place):

Suggested change

The second argument passed to `createExports()` can be useful when you need to access build-time configuration in your server entrypoint. For example, your server entrypoint might need the directory path in the build output where the resources generated by Astro are located:

You can access the [`args`](#args) defined by your adapter through the second argument of `createExports()`. This can be useful when you need to access build-time configuration in your server entrypoint. For example, your server might need to identify where assets generated by Astro are located:

Edit: updated with Sarah's most recent suggestion

src/content/docs/en/reference/adapter-reference.mdx

florian-lefebvre · 2025-11-07T12:38:30Z

Re app.setManifestData: I think it should be removed indeed, no match on GitHub either. I'll add it to the v6 milestone

sarah11918 · 2025-11-07T12:45:28Z

src/content/docs/en/reference/adapter-reference.mdx

+
+A JSON-serializable value that will be passed to the adapter's server entrypoint at runtime. This is useful to pass an object containing build-time configuration (e.g. paths, secrets, etc.) to your server runtime code.
+
+The following example defines an `args` object to pass to [the server entrypoint](#building-a-server-entrypoint) the directory path in the build output where the resources generated by Astro are located:


There is something not quite grammatical about this. So I tried to figure out what this was saying. When you break it down, it says:

Suggested change

The following example defines an `args` object to pass to [the server entrypoint](#building-a-server-entrypoint) the directory path in the build output where the resources generated by Astro are located:

The following example defines an `args` object with the directory path in the build output for the location of the resources generated by Astro:

Is config.build.assets a directory path? (it doesn't look like a path in the file tree/URL sense (`///), but I'm not familiar with this usage so it is probably fine. Just checking!)

It's also true that it's being passed to the server entry point, but a) you already defined args as something that gets passed to a server entry point and b) that makes this sentence more complicated to include the thing that you are passing and what you're passing it to. So, it's probably clearer not to mention that so that this can focus on helping make sense of what args is/does.

So, is the above correct? (Because that's what you've said.) If not, how does it need to change?

The args property was the hardest to understand (this is not the easiest word to look for in a codebase 😆), so this section may not be the most accurate.

Is config.build.assets a directory path?

I'm honestly not sure what is the actual value. Reading the configuration reference, that could be only the directory name. I don't know if there is some kind of internal resolution to turn it in a relative/absolute path.

So, your suggestion sounds good to me! I wasn't fan of my version but couldn't find a better wording. 😅
I'm not committing it yet in case someone else want to answer your question/if there is anything to improve regarding that.

Maybe @ascorbic or @florian-lefebvre can clarify what args is: a path? a directory?

Basically args can be anything (as long as it's serializable)! It's just data you want to get in createExports(), for example: https://github.com/withastro/astro/blob/7b7e037e435488227a361dcbe89a0a44d327c2c4/packages/integrations/node/src/server.ts#L16

I think "the directory path in the build output where the resources generated by Astro are located" is too confusing and shoulkd be removed. It's just an example of the sort of thing that could be passed in.

Suggested change

The following example defines an `args` object to pass to [the server entrypoint](#building-a-server-entrypoint) the directory path in the build output where the resources generated by Astro are located:

The following example defines an `args` object to identify where assets generated by Astro are located:

Would this maybe be accurate and "good enough" then? Or

"... defines an args object to provide additional information about assets generated by Astro"

?

Suggested change

The following example defines an `args` object to pass to [the server entrypoint](#building-a-server-entrypoint) the directory path in the build output where the resources generated by Astro are located:

The following example defines an `args` object with a property that identifies where assets generated by Astro are located:

src/content/docs/en/reference/adapter-reference.mdx

sarah11918 · 2025-11-07T12:54:22Z

src/content/docs/en/reference/adapter-reference.mdx

+## Building a server entrypoint

-```js
+Astro's adapter API attempts to work with any type of host, and gives a flexible way to conform to the host APIs.


Suggested change

Astro's adapter API attempts to work with any type of host, and gives a flexible way to conform to the host APIs.

You will need to create a file that executes during server-side requests to enable on-demand rendering with your particular host. Astro's adapter API attempts to work with any type of host, and gives a flexible way to conform to the host APIs.

Feels like something like this is kind of needed here? I just took phrases from various places, so make this make sense 😂

Anyone? Suggestions for this?

I preferred to wait before committing it in case one of our adapter experts wanted to check the accuracy, but great idea! And this sounds correct to me.

src/content/docs/en/reference/adapter-reference.mdx

Co-authored-by: Matt Kane <[email protected]> Co-authored-by: Sarah Rainsberger <[email protected]>

Co-authored-by: Sarah Rainsberger <[email protected]>

Co-authored-by: Armand Philippot <[email protected]>

sarah11918 · 2025-11-07T14:11:36Z

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 · 2025-11-07T16:30:03Z

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

refactor(adapter-reference): type code block to docs + reorganization

0e857ee

ArmandPhilippot added 12 commits November 5, 2025 16:56

restore Astro features and Adapter features sections

9495dac

add missing public APIs for astro/app

97b9926

fix heading levels now that the features sections are restored

5011db4

RenderOptions can now be nested in app.render

9cafe3f

small rewording

1978fa2

add docs for args

a7eacaa

improve setCookieHeaders docs

e704ee6

remove app.setManifestData (leftover or internal thing I think)

c676cc1

add code snippets for setAdapter properties

534e2e8

adds docs for createExports second argument

575b23a

update server entrypoint exports and start sections

d38ac58

fix link, should be ready now

cb92f38

ArmandPhilippot marked this pull request as ready for review November 6, 2025 16:53

ascorbic reviewed Nov 7, 2025

View reviewed changes

ArmandPhilippot and others added 2 commits November 7, 2025 12:06

Matt's wording improvement

9a9081e

Co-authored-by: Matt Kane <[email protected]>

add handler in createExports args snippet

5041d53

Co-authored-by: Matt Kane <[email protected]>