From abffa8067073a1c05c67f15a6600dc18653c5ccd Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 16 Sep 2024 23:42:09 +0200 Subject: [PATCH 1/5] fix: v5/format-adapter-reference.mdx --- .../docs/en/reference/adapter-reference.mdx | 94 +++++++++++++++---- 1 file changed, 78 insertions(+), 16 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 3136128d947a5..ef7e95e44a047 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -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,7 +50,7 @@ interface AstroAdapter { exports?: string[]; args?: any; adapterFeatures?: AstroAdapterFeatures; - supportedAstroFeatures?: AstroFeatureMap; + supportedAstroFeatures: AstroAdapterFeatureMap; } export interface AstroAdapterFeatures { @@ -58,18 +58,22 @@ 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'; } -export type SupportsKind = 'unsupported' | 'stable' | 'experimental' | 'deprecated'; +export type AdapterSupportsKind = 'unsupported' | 'stable' | 'experimental' | 'deprecated' | 'limited'; export type AdapterSupportWithMessage = { - support: Exclude; + support: Exclude; message: string; }; -export type AdapterSupport = SupportsKind | AdapterSupportWithMessage; +export type AdapterSupport = AdapterSupportsKind | AdapterSupportWithMessage; -export type AstroFeatureMap = { +export type AstroAdapterFeatureMap = { /** * 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; /** * 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()` + +

+ +**Type:** `(request: Request, options?: RenderOptions) => Promise` +

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` +

+ +**Type:** `{addCookieHeader?: boolean; clientAddress?: string; locals?: object; routeData?: RouteData;}` +

+ 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` +

+ +**Type:** `boolean`
+**Default:** `false` +

+ 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` +

+ +**Type:** `string`
+**Default:** `request[Symbol.for("astro.clientAddress")]` +

+ 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` +

+ +**Type:** `object` +

+ 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` +

+ +**Type:** `RouteData`
+**Default:** `app.match(request)` +

+ 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()` + +

+ +**Type:** `(request: Request) => RouteData | undefined` +

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

@@ -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', @@ -318,7 +364,7 @@ Astro will log a **warning** to the terminal: [@matthewp/my-adapter] The feature is experimental and subject to issues or changes. ``` -and an error if the Sharp image service is used and is not compatible with the adapter: +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. @@ -326,7 +372,7 @@ and an error if the Sharp image service is used and is not compatible with the a 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 +400,13 @@ A set of features that changes the output of the emitted files. When an adapter ### `edgeMiddleware` +

+ +**Type:** `boolean` +

+ 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} @@ -411,6 +462,11 @@ function createEdgeMiddleware(middlewareEntryPoint) { ### envGetSecret +

+ +**Type:** `SupportsKind` +

+ 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: @@ -482,6 +538,12 @@ export function createExports(manifest: SSRManifest) { ### buildOutput +

+ +**Type:** `'static' | 'server'`
+ +

+ 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} From 86874a8cafa2b641bfed312f6bc8aa27655287de Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 17 Sep 2024 00:26:23 +0200 Subject: [PATCH 2/5] fix code block highlighting for `astro:build:ssr` --- src/content/docs/en/reference/adapter-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index ef7e95e44a047..efcf392bb6e76 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -430,7 +430,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', From e80da387a200210c50a8ecb4c9c7866b28a822f1 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 17 Sep 2024 11:54:54 +0200 Subject: [PATCH 3/5] fix `envGetSecret` type --- src/content/docs/en/reference/adapter-reference.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index efcf392bb6e76..0cc2e1d4bd1f2 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -464,12 +464,12 @@ function createEdgeMiddleware(middlewareEntryPoint) {

-**Type:** `SupportsKind` +**Type:** `AdapterSupportsKind`

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() { From 18641b7ed7ce4454291d453b33208013354d6eb2 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 17 Sep 2024 19:15:31 +0200 Subject: [PATCH 4/5] question mark Co-authored-by: Sarah Rainsberger --- src/content/docs/en/reference/adapter-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 0cc2e1d4bd1f2..734c96f8c1e04 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -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: From dc4b69364a9600b1c3f3ac51725b71accf79b194 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 17 Sep 2024 19:18:00 +0200 Subject: [PATCH 5/5] remove unecessary line break in middle of a sentence Co-authored-by: Sarah Rainsberger --- src/content/docs/en/reference/adapter-reference.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 734c96f8c1e04..2f1bc38dd70f8 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -358,15 +358,11 @@ 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. -``` - -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. ```