Skip to content
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

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 80 additions & 22 deletions src/content/docs/en/reference/adapter-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -50,26 +50,30 @@ interface AstroAdapter {
exports?: string[];
args?: any;
adapterFeatures?: AstroAdapterFeatures;
supportedAstroFeatures?: AstroFeatureMap;
supportedAstroFeatures: AstroAdapterFeatureMap;
Copy link
Member Author

Choose a reason for hiding this comment

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

This was renamed.

}

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

Choose a reason for hiding this comment

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

buildOuput was missing.

}

export type SupportsKind = 'unsupported' | 'stable' | 'experimental' | 'deprecated';
export type AdapterSupportsKind = 'unsupported' | 'stable' | 'experimental' | 'deprecated' | 'limited';
Copy link
Member Author

Choose a reason for hiding this comment

The 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 = {
Copy link
Member Author

Choose a reason for hiding this comment

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

This was renamed.

/**
* The adapter is able to serve static pages
*/
Expand All @@ -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
Copy link
Member Author

@ArmandPhilippot ArmandPhilippot Sep 16, 2024

Choose a reason for hiding this comment

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

i18nDomains was missing and I moved envGetSecret (while fixing the comment).

/**
* The adapter supports the Sharp image service
*/
sharpImageService?: AdapterSupport;
* The adapter supports `astro:env` secrets
*/
envGetSecret?: AdapterSupport;
};
```

Expand Down Expand Up @@ -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.

Expand All @@ -197,10 +211,21 @@ const response = await app.render(request);

##### `RenderOptions`

<p>

**Type:** `{addCookieHeader?: boolean; clientAddress?: string; locals?: object; routeData?: RouteData;}`
Copy link
Member Author

Choose a reason for hiding this comment

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

</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.
Expand All @@ -212,6 +237,12 @@ const response = await app.render(request, { addCookieHeader: true });

###### `clientAddress`

<p>

**Type:** `string`<br />
**Default:** `request[Symbol.for("astro.clientAddress")]`
Copy link
Member Author

@ArmandPhilippot ArmandPhilippot Sep 16, 2024

Choose a reason for hiding this comment

The 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`.
Expand All @@ -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/).
Expand All @@ -241,6 +277,12 @@ try {

###### `routeData`

<p>

**Type:** `RouteData`<br />
**Default:** `app.match(request)`
Copy link
Member Author

@ArmandPhilippot ArmandPhilippot Sep 16, 2024

Choose a reason for hiding this comment

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

It seems the default is the return type of app.match(request) and not app.match(request). But I wasn't sure about the value, maybe RouteData | undefined but it does not make sense as Default....

Copy link
Member

Choose a reason for hiding this comment

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

Should this now be IntegrationRouteData?

Copy link
Member Author

Choose a reason for hiding this comment

The 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:

  • By switching back to the next branch: the type is still RouteData.
  • So I checked IntegrationRouteData to make sure it's not an alias: this is a smaller version of RouteData.

So I don't think so, RouteData type still exists and it seems to be the one expected. And I guess the sentence below remains valid: we provide a full RouteData object which is passed to integrationRouteData in its smaller form.
But a check from someone more informed on how it works may be useful, this is marked as **Advanced API**: you probably do not need to use this.

Copy link
Member

Choose a reason for hiding this comment

The 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"
Expand All @@ -253,7 +295,12 @@ if (routeData) {
}
```

##### `app.match(request)`
##### `app.match()`

<p>

**Type:** `(request: Request) => RouteData | undefined`
Copy link
Member Author

Choose a reason for hiding this comment

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

</p>

This method is used to determine if a request is matched by the Astro app's routing rules.

Expand All @@ -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>
Expand All @@ -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',
Expand All @@ -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',
Expand Down Expand Up @@ -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}
Expand All @@ -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',
Expand Down Expand Up @@ -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() {
Expand Down Expand Up @@ -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}
Expand Down
Loading