From fe2063577fa5d6271a27586d3917ff0fcf8825b7 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Mon, 10 Jul 2023 09:47:42 +0100 Subject: [PATCH 01/10] feat: document `locals` in adapter API --- .../docs/en/reference/adapter-reference.mdx | 20 ++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index b50e7c6dfef3e..49b89a44b486b 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -136,7 +136,7 @@ export function start(manifest) { The following methods are provided: -##### `app.render(request)` +##### `app.render(request, routeData, locals)` 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. @@ -144,6 +144,24 @@ This method calls the Astro page that matches the request, renders it, and retur const response = await app.render(request); ``` +The method accepts a mandatory `request` arguments, and two other optionals arguments: `routeData` and `locals`. + +[//]: # (TODO) document `routeData` + +`locals` is an optional object to pass to the adapter. This object will be passed to any [middleware function](/en/guides/middleware/). + +```js +const privateHeader = request.headers.get("x-private-header"); +let locals = {}; +try { + if (privateHeader) { + locals = JSON.parse(privateHeader); + } +} finally { + const response = await app.render(request, undefined, locals); +} +``` + ##### `app.match(request)` This method is used to determine if a request is matched by the Astro app's routing rules. From f9ef0203d7d1222e15a484b303ff496e19653b69 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Mon, 10 Jul 2023 11:49:36 +0100 Subject: [PATCH 02/10] Apply suggestions from code review Co-authored-by: Sarah Rainsberger --- src/content/docs/en/reference/adapter-reference.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 49b89a44b486b..7468d0789a89b 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -138,17 +138,15 @@ The following methods are provided: ##### `app.render(request, routeData, locals)` -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. +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. ```js const response = await app.render(request); ``` -The method accepts a mandatory `request` arguments, and two other optionals arguments: `routeData` and `locals`. +The method accepts a mandatory `request` argument, and two other optionals arguments: [`routeData`](en/reference/integrations-reference/#routedata-type-reference) and [`locals`](https://docs.astro.build/en/guides/middleware/#locals). -[//]: # (TODO) document `routeData` - -`locals` is an optional object to pass to the adapter. This object will be passed to any [middleware function](/en/guides/middleware/). +The example below reads a header named `x-private-hader`, which attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). ```js const privateHeader = request.headers.get("x-private-header"); From 670379d05859ea9773f4270d06ce0eff53c422e1 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Mon, 10 Jul 2023 11:50:02 +0100 Subject: [PATCH 03/10] Apply suggestions from code review --- 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 7468d0789a89b..97127cea9e4da 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -146,7 +146,7 @@ const response = await app.render(request); The method accepts a mandatory `request` argument, and two other optionals arguments: [`routeData`](en/reference/integrations-reference/#routedata-type-reference) and [`locals`](https://docs.astro.build/en/guides/middleware/#locals). -The example below reads a header named `x-private-hader`, which attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). +The example below reads a header named `x-private-header`, which attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). ```js const privateHeader = request.headers.get("x-private-header"); From 9dfc92bfe0e81ae5dc73eb3c747c870d70580af2 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 10 Jul 2023 08:12:57 -0300 Subject: [PATCH 04/10] bad link form --- 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 97127cea9e4da..55faa4468ba28 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -144,7 +144,7 @@ This method calls the Astro page that matches the request, renders it, and retur const response = await app.render(request); ``` -The method accepts a mandatory `request` argument, and two other optionals arguments: [`routeData`](en/reference/integrations-reference/#routedata-type-reference) and [`locals`](https://docs.astro.build/en/guides/middleware/#locals). +The method accepts a mandatory `request` argument, and two other optionals arguments: [`routeData`](en/reference/integrations-reference/#routedata-type-reference) and [`locals`](/en/guides/middleware/#locals). The example below reads a header named `x-private-header`, which attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). From 7e842b0fa4e9e231f2b9761f5c2cbf28830359ae Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 10 Jul 2023 09:47:27 -0300 Subject: [PATCH 05/10] stupid link again --- 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 55faa4468ba28..d6255fc13176e 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -144,7 +144,7 @@ This method calls the Astro page that matches the request, renders it, and retur const response = await app.render(request); ``` -The method accepts a mandatory `request` argument, and two other optionals arguments: [`routeData`](en/reference/integrations-reference/#routedata-type-reference) and [`locals`](/en/guides/middleware/#locals). +The method accepts a mandatory `request` argument, and two other optionals arguments: [`routeData`](/en/reference/integrations-reference/#routedata-type-reference) and [`locals`](/en/guides/middleware/#locals). The example below reads a header named `x-private-header`, which attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). From ed5e144b67a0eb2cb3887e8906d030b175412e6f Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Mon, 10 Jul 2023 10:04:28 -0300 Subject: [PATCH 06/10] Yan's proofreading is not `optional`! Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> --- 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 d6255fc13176e..0ffeaa3bbcff0 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -144,7 +144,7 @@ This method calls the Astro page that matches the request, renders it, and retur const response = await app.render(request); ``` -The method accepts a mandatory `request` argument, and two other optionals arguments: [`routeData`](/en/reference/integrations-reference/#routedata-type-reference) and [`locals`](/en/guides/middleware/#locals). +The method accepts a mandatory `request` argument, and two other optional arguments: [`routeData`](/en/reference/integrations-reference/#routedata-type-reference) and [`locals`](/en/guides/middleware/#locals). The example below reads a header named `x-private-header`, which attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). From b03f4a9a9092ed70194badfc3e91fb34f4fc6e2a Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Mon, 10 Jul 2023 15:22:40 +0100 Subject: [PATCH 07/10] Update src/content/docs/en/reference/adapter-reference.mdx 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 0ffeaa3bbcff0..e80898eee5926 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -146,7 +146,7 @@ const response = await app.render(request); The method accepts a mandatory `request` argument, and two other optional arguments: [`routeData`](/en/reference/integrations-reference/#routedata-type-reference) and [`locals`](/en/guides/middleware/#locals). -The example below reads a header named `x-private-header`, which attempts to parse it as an object and pass it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/). +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/). ```js const privateHeader = request.headers.get("x-private-header"); From 3a6c060f8e909b9686add87aa858d38f2ddbc0d0 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Fri, 14 Jul 2023 15:33:52 +0100 Subject: [PATCH 08/10] add small info about the second argument --- src/content/docs/en/reference/adapter-reference.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index e80898eee5926..5552ad7059f05 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -146,6 +146,8 @@ const response = await app.render(request); The method accepts a mandatory `request` argument, and two other optional arguments: [`routeData`](/en/reference/integrations-reference/#routedata-type-reference) and [`locals`](/en/guides/middleware/#locals). +Use the first argument when you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatchrequest) to determine the route to render. + 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/). ```js From 89e241d5c87d17345de65564213617443379eec1 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Tue, 18 Jul 2023 08:46:28 +0100 Subject: [PATCH 09/10] Update src/content/docs/en/reference/adapter-reference.mdx 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 5552ad7059f05..c0e6b1d8f66e4 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -146,7 +146,7 @@ const response = await app.render(request); The method accepts a mandatory `request` argument, and two other optional arguments: [`routeData`](/en/reference/integrations-reference/#routedata-type-reference) and [`locals`](/en/guides/middleware/#locals). -Use the first argument when you already know the route to render. Doing so will bypass the internal call to [`app.match`](#appmatchrequest) to determine the route to render. +Provide a value for `routeData` 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. 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/). From 6654313c089acdf33f14174fb5be5fcd314c0e6a Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Tue, 18 Jul 2023 07:08:16 -0300 Subject: [PATCH 10/10] explain order of arguments --- src/content/docs/en/reference/adapter-reference.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index c0e6b1d8f66e4..f7ed4c3cdfc17 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -148,6 +148,8 @@ The method accepts a mandatory `request` argument, and two other optional argume Provide a value for `routeData` 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. +When used, `locals` must be the third argument passed. You can pass `undefined` for `routeData` if you are not targeting a specific route. + 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/). ```js