-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
fix(v5): format adapter-reference.mdx
#9423
Changes from all commits
abffa80
86874a8
e80da38
18641b7
dc4b693
df9c8d6
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -8,7 +8,7 @@ import { FileTree } from '@astrojs/starlight/components'; | |
|
||
Astro is designed to make it easy to deploy to any cloud provider for SSR (server-side rendering). This ability is provided by __adapters__, which are [integrations](/en/reference/integrations-reference/). See the [SSR guide](/en/guides/on-demand-rendering/) to learn how to use an existing adapter. | ||
|
||
## What is an adapter | ||
## What is an adapter? | ||
|
||
An adapter is a special kind of [integration](/en/reference/integrations-reference/) that provides an entrypoint for server-side rendering. An adapter does two things: | ||
|
||
|
@@ -50,26 +50,30 @@ interface AstroAdapter { | |
exports?: string[]; | ||
args?: any; | ||
adapterFeatures?: AstroAdapterFeatures; | ||
supportedAstroFeatures?: AstroFeatureMap; | ||
supportedAstroFeatures: AstroAdapterFeatureMap; | ||
} | ||
|
||
export interface AstroAdapterFeatures { | ||
/** | ||
* Creates an edge function that will communicate with the Astro middleware. | ||
*/ | ||
edgeMiddleware: boolean; | ||
/** | ||
* Determine the type of build output the adapter is intended for. Defaults to `server`; | ||
*/ | ||
buildOutput?: 'static' | 'server'; | ||
Comment on lines
+61
to
+64
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
} | ||
|
||
export type SupportsKind = 'unsupported' | 'stable' | 'experimental' | 'deprecated'; | ||
export type AdapterSupportsKind = 'unsupported' | 'stable' | 'experimental' | 'deprecated' | 'limited'; | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This was renamed. |
||
|
||
export type AdapterSupportWithMessage = { | ||
support: Exclude<SupportsKind, 'stable'>; | ||
support: Exclude<AdapterSupportsKind, 'stable'>; | ||
message: string; | ||
}; | ||
|
||
export type AdapterSupport = SupportsKind | AdapterSupportWithMessage; | ||
export type AdapterSupport = AdapterSupportsKind | AdapterSupportWithMessage; | ||
|
||
export type AstroFeatureMap = { | ||
export type AstroAdapterFeatureMap = { | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This was renamed. |
||
/** | ||
* The adapter is able to serve static pages | ||
*/ | ||
|
@@ -82,13 +86,18 @@ export type AstroFeatureMap = { | |
* The adapter is able to serve SSR pages | ||
*/ | ||
serverOutput?: AdapterSupport; | ||
/** | ||
* The adapter is able to support i18n domains | ||
*/ | ||
i18nDomains?: AdapterSupport; | ||
/** | ||
* The adapter is able to support `getSecret` exported from `astro:env/server` | ||
*/ | ||
envGetSecret?: AdapterSupport; | ||
Comment on lines
+89
to
+96
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
/** | ||
* The adapter supports the Sharp image service | ||
*/ | ||
sharpImageService?: AdapterSupport; | ||
* The adapter supports `astro:env` secrets | ||
*/ | ||
envGetSecret?: AdapterSupport; | ||
}; | ||
``` | ||
|
||
|
@@ -187,7 +196,12 @@ export function start(manifest) { | |
|
||
The following methods are provided: | ||
|
||
##### `app.render(request: Request, options?: RenderOptions)` | ||
##### `app.render()` | ||
|
||
<p> | ||
|
||
**Type:** `(request: Request, options?: RenderOptions) => Promise<Response>` | ||
</p> | ||
|
||
This method calls the Astro page that matches the request, renders it, and returns a Promise to a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object. This also works for API routes that do not render pages. | ||
|
||
|
@@ -197,10 +211,21 @@ const response = await app.render(request); | |
|
||
##### `RenderOptions` | ||
|
||
<p> | ||
|
||
**Type:** `{addCookieHeader?: boolean; clientAddress?: string; locals?: object; routeData?: RouteData;}` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You can check the type here. |
||
</p> | ||
|
||
The `app.render()` method accepts a mandatory `request` argument, and an optional `RenderOptions` object for [`addCookieHeader`](#addcookieheader), [`clientAddress`](#clientaddress), [`locals`](#locals), and [`routeData`](#routedata). | ||
|
||
###### `addCookieHeader` | ||
|
||
<p> | ||
|
||
**Type:** `boolean`<br /> | ||
**Default:** `false` | ||
</p> | ||
|
||
Whether or not to automatically add all cookies written by `Astro.cookie.set()` to the response headers. | ||
|
||
When set to `true`, they will be added to the `Set-Cookie` header of the response as comma separated key-value pairs. You can use the standard `response.headers.getSetCookie()` API to read them individually. | ||
|
@@ -212,6 +237,12 @@ const response = await app.render(request, { addCookieHeader: true }); | |
|
||
###### `clientAddress` | ||
|
||
<p> | ||
|
||
**Type:** `string`<br /> | ||
**Default:** `request[Symbol.for("astro.clientAddress")]` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Not sure if this default is really useful... |
||
</p> | ||
|
||
The client IP address that will be made available as [`Astro.clientAddress`](/en/reference/api-reference/#astroclientaddress) in pages, and as `ctx.clientAddress` in API routes and middleware. | ||
|
||
The example below reads the `x-forwarded-for` header and passes it as `clientAddress`. This value becomes available to the user as `Astro.clientAddress`. | ||
|
@@ -223,6 +254,11 @@ const response = await app.render(request, { clientAddress }); | |
|
||
###### `locals` | ||
|
||
<p> | ||
|
||
**Type:** `object` | ||
</p> | ||
|
||
The [`context.locals` object](/en/reference/api-reference/#contextlocals) used to store and access information during the lifecycle of a request. | ||
|
||
The example below reads a header named `x-private-header`, attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). | ||
|
@@ -241,6 +277,12 @@ try { | |
|
||
###### `routeData` | ||
|
||
<p> | ||
|
||
**Type:** `RouteData`<br /> | ||
**Default:** `app.match(request)` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It seems the default is the return type of There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should this now be There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I hadn't paid attention to the sentence below, so I understand your question... I checked again:
So I don't think so, There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ok, then sounds good! Thank you! |
||
</p> | ||
|
||
Provide a value for [`integrationRouteData`](/en/reference/integrations-reference/#integrationroutedata-type-reference) if you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatchrequest) to determine the route to render. | ||
|
||
```js "routeData" | ||
|
@@ -253,7 +295,12 @@ if (routeData) { | |
} | ||
``` | ||
|
||
##### `app.match(request)` | ||
##### `app.match()` | ||
|
||
<p> | ||
|
||
**Type:** `(request: Request) => RouteData | undefined` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You can check the type here. |
||
</p> | ||
|
||
This method is used to determine if a request is matched by the Astro app's routing rules. | ||
|
||
|
@@ -278,7 +325,6 @@ You can usually call `app.render(request)` without using `.match` because Astro | |
|
||
Once you [publish your adapter to npm](https://docs.npmjs.com/cli/v8/commands/npm-publish), running `astro add example` will install your package with any peer dependencies specified in your `package.json`. We will also instruct users to update their project config manually. | ||
|
||
|
||
## Astro features | ||
|
||
<p><Since v="3.0.0" /></p> | ||
|
@@ -293,7 +339,7 @@ These operations are run based on the features supported or not supported, their | |
|
||
The following configuration tells Astro that this adapter has experimental support for the Sharp-powered built-in image service: | ||
|
||
```js title="my-adapter.mjs" ins={9-15} | ||
```js title="my-adapter.mjs" ins={9-11} | ||
export default function createIntegration() { | ||
return { | ||
name: '@matthewp/my-adapter', | ||
|
@@ -312,21 +358,17 @@ export default function createIntegration() { | |
} | ||
``` | ||
|
||
Astro will log a **warning** to the terminal: | ||
If the Sharp image service is used, Astro will log a warning and error to the terminal based on your adapter's support: | ||
|
||
``` | ||
[@matthewp/my-adapter] The feature is experimental and subject to issues or changes. | ||
ArmandPhilippot marked this conversation as resolved.
Show resolved
Hide resolved
|
||
``` | ||
|
||
and an error if the Sharp image service is used and is not compatible with the adapter: | ||
|
||
``` | ||
[@matthewp/my-adapter] The currently selected adapter `@matthewp/my-adapter` is not compatible with the service "Sharp". Your project will NOT be able to build. | ||
``` | ||
|
||
A message can additionally be provided to give more context to the user: | ||
|
||
```js title="my-adapter.mjs" ins={9-15} | ||
```js title="my-adapter.mjs" ins={9-14} | ||
export default function createIntegration() { | ||
return { | ||
name: '@matthewp/my-adapter', | ||
|
@@ -354,8 +396,13 @@ A set of features that changes the output of the emitted files. When an adapter | |
|
||
### `edgeMiddleware` | ||
|
||
<p> | ||
|
||
**Type:** `boolean` | ||
</p> | ||
|
||
Defines whether any SSR middleware code will be bundled when built. | ||
|
||
When enabled, this prevents middleware code from being bundled and imported by all pages during the build: | ||
|
||
```js title="my-adapter.mjs" ins={9-11} | ||
|
@@ -379,7 +426,7 @@ export default function createIntegration() { | |
|
||
Then, consume the hook [`astro:build:ssr`](/en/reference/integrations-reference/#astrobuildssr), which will give you a `middlewareEntryPoint`, an `URL` to the physical file on the file system. | ||
|
||
```js title="my-adapter.mjs" ins={15-19} | ||
```js title="my-adapter.mjs" ins={15-20} | ||
export default function createIntegration() { | ||
return { | ||
name: '@matthewp/my-adapter', | ||
|
@@ -411,9 +458,14 @@ function createEdgeMiddleware(middlewareEntryPoint) { | |
|
||
### envGetSecret | ||
|
||
<p> | ||
|
||
**Type:** `AdapterSupportsKind` | ||
</p> | ||
|
||
This is a feature to allow your adapter to retrieve secrets configured by users in `env.schema`. | ||
|
||
Enable the feature by passing any valid `SupportsKind` value to the adapter: | ||
Enable the feature by passing any valid `AdapterSupportsKind` value to the adapter: | ||
|
||
```js title="my-adapter.mjs" ins={9-11} | ||
export default function createIntegration() { | ||
|
@@ -482,6 +534,12 @@ export function createExports(manifest: SSRManifest) { | |
|
||
### buildOutput | ||
|
||
<p> | ||
|
||
**Type:** `'static' | 'server'`<br /> | ||
<Since v="5.0.0" /> | ||
</p> | ||
|
||
This property allows you to force a specific output shape for the build. This can be useful for adapters that only work with a specific output type, for instance, your adapter might expect a static website, but uses an adapter to create host-specific files. Defaults to `server` if not specified. | ||
|
||
```js title="my-adapter.mjs" ins={9-11} | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This was renamed.