Skip to content
Open
Show file tree
Hide file tree
Changes from 11 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
8 changes: 4 additions & 4 deletions src/content/docs/en/guides/integrations-guide/netlify.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -98,9 +98,9 @@ The [Netlify Blog post on Astro](https://www.netlify.com/blog/how-to-deploy-astr

### Running Astro middleware on Netlify Edge Functions

Any Astro middleware is applied to pre-rendered pages at build-time, and to on-demand-rendered pages at runtime.
By default, Astro middleware is applied to pre-rendered pages at build-time and to on-demand-rendered pages at runtime.

To implement redirects, access control, or custom response headers for pre-rendered pages, run your middleware on Netlify Edge Functions by enabling the [`edgeMiddleware` option](/en/reference/adapter-reference/#edgemiddleware):
To implement redirects, access control, or custom response headers for pre-rendered pages, run your middleware on Netlify Edge Functions by setting the [`middlewareMode` option](/en/reference/adapter-reference/#middlewaremode) to `edge`:

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
Expand All @@ -109,12 +109,12 @@ import netlify from '@astrojs/netlify';
export default defineConfig({
// ...
adapter: netlify({
edgeMiddleware: true,
middlewareMode: 'edge',
}),
});
```

When `edgeMiddleware` is enabled, an edge function will execute your middleware code for all requests including static assets, prerendered pages, and on-demand rendered pages.
When `middlewareMode` is set to `'edge'`, an edge function will execute your middleware code for all requests, including static assets, prerendered pages, and on-demand rendered pages.

For on-demand rendered pages, the `context.locals` object is serialized using JSON and sent in a header for the serverless function, which performs the rendering. As a security measure, the serverless function will refuse to serve requests with a `403 Forbidden` response unless they come from the generated edge function.

Expand Down
8 changes: 4 additions & 4 deletions src/content/docs/en/guides/integrations-guide/vercel.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -442,20 +442,20 @@ export default defineConfig({

### Running Astro middleware on Vercel Edge Functions

The `@astrojs/vercel` adapter can create an [edge function](https://vercel.com/docs/functions/edge-functions) from an Astro middleware in your code base. When `edgeMiddleware` is enabled, an edge function will execute your middleware code for all requests including static assets, prerendered pages, and on-demand rendered pages.
The `@astrojs/vercel` adapter can create an [edge function](https://vercel.com/docs/functions/edge-functions) from an Astro middleware in your code base. When [`middlewareMode`](/en/reference/adapter-reference/#middlewaremode) is set to `'edge'`, an edge function will execute your middleware code for all requests including static assets, prerendered pages, and on-demand rendered pages.

For on-demand rendered pages, the `context.locals` object is serialized using JSON and sent in a header for the serverless function, which performs the rendering. As a security measure, the serverless function will refuse to serve requests with a `403 Forbidden` response unless they come from the generated edge function.

This is an opt-in feature. To enable it, set `edgeMiddleware` to `true`:
This is an opt-in feature. To enable it, set `middlewareMode` to `'edge'`:

```js title="astro.config.mjs" "edgeMiddleware: true"
```js title="astro.config.mjs" "middlewareMode: 'edge'"
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel';

export default defineConfig({
// ...
adapter: vercel({
edgeMiddleware: true,
middlewareMode: 'edge',
}),
});
```
Expand Down
26 changes: 20 additions & 6 deletions src/content/docs/en/reference/adapter-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -1041,16 +1041,20 @@ Defines whether the adapter supports image transformation using the built-in Sha

A set of features that changes the output of the emitted files. When an adapter opts in to these features, they will get additional information inside specific hooks and must implement the proper logic to handle the different output.

### `edgeMiddleware`
### `middlewareMode`
Copy link
Member

Choose a reason for hiding this comment

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

Noting that this is causing a link failure in /ja/ where this is translated and the Netlify guide is linking here.

Would be great if @jp-knj or @morinokami could jump in here! We can translate just the heading, then use that as the anchor link on the Netlify page (but still mark this as [i18nIgnore] so that it's clear the pages do still need the regular updates.

One thing we could do that doesn't have to include any translations yet, since the Netlify guide will need to update anyway is that this PR could temporarily just update the ja adapter page to say (in English) "middlewareMode", and then we hard code the English slug in the broken link. When the translators go to update the Netlify page, they can also change the English heading and slug to translations. (note this would still require [i18nIgnore] in the subject because we would have touched those /ja/ files)


<p>

**Type:** `boolean`
**Type:** [`MiddlewareMode`](#middlewaremode-1)<br />
**Default:** `"classic"`<br />
<Since v="6.0.0" />
</p>

Defines whether any on-demand rendering middleware code will be bundled when built.
Determines at which stage of the page lifecycle the middleware is executed, and how the middleware code is emitted in the build output.

The `classic` mode matches the default behavior of Astro. On prerendered pages, middleware is run at build time, and when the page is requested, the middleware is not run again. On dynamic pages, middleware is run at request time only. The middleware code is part of your server bundle.

When enabled, this prevents middleware code from being bundled and imported by all pages during the build:
In `edge` mode, the middleware code can be deployed independently from the server bundle, for example, as an edge function.

```js title="my-adapter.mjs" ins={10-12}
export default function createIntegration() {
Expand All @@ -1063,7 +1067,7 @@ export default function createIntegration() {
entrypointResolution: 'auto',
serverEntrypoint: '@example/my-adapter/server.js',
adapterFeatures: {
edgeMiddleware: true
middlewareMode: 'edge'
}
});
},
Expand All @@ -1085,7 +1089,7 @@ export default function createIntegration() {
entrypointResolution: 'auto',
serverEntrypoint: '@example/my-adapter/server.js',
adapterFeatures: {
edgeMiddleware: true
middlewareMode: 'edge'
}
});
},
Expand Down Expand Up @@ -1287,6 +1291,16 @@ export default function createIntegration() {
}
```

### `MiddlewareMode`
Copy link
Member

Choose a reason for hiding this comment

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

@ArmandPhilippot I'll ask for your guidance here. Somehow it feels less helpful to have such a short entry here that actually tells people which values they can set as a middleware mode? I would think that that it's more valuable that in the entry above for the config option, people can very quickly see "oh, it's classic or edge!" rather than see "Oh, middleware mode is a middleware mode" then need to follow a trail to get here?

But, what do you think?

Copy link
Member

Choose a reason for hiding this comment

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

My take would be: Is this type useful so that the user can use it elsewhere (for example, a helper function) or is it only useful in this specific case? I would say the second one here, but I'm not an adapter builder so I could be wrong.

If there are use cases for the type, while I agree with Sarah, I think this can helpful to have an entry for it (so people know they can import it). Otherwise, yes, we probably don't need this and we can replace MiddlewareMode with "classic" | "edge" in the property type!

Copy link
Author

Choose a reason for hiding this comment

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

Use case would mainly be for adapter developers, to expose this as a property on the adapter. I'd recommend using the type over hardcoding it, since it is going to change in the (near) future.


<p>

**Type:** `"classic" | "edge"`<br />
<Since v="6.0.0" />
</p>

A union of valid formats to describe the mode in which middleware is run.

## Allow installation via `astro add`

[The `astro add` command](/en/reference/cli-reference/#astro-add) allows users to easily add integrations and adapters to their project. To allow your adapter to be installed with this command, **add `astro-adapter` to the `keywords` field in your `package.json`**:
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/ja/guides/integrations-guide/netlify.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@

Astroミドルウェアは、ビルド時に事前レンダリングされたページに、実行時にオンデマンドでレンダリングされたページに適用されます。

事前レンダリングされたページのリダイレクト、アクセス制御、またはカスタムレスポンスヘッダーを実装するには、[`edgeMiddleware`オプション](/ja/reference/adapter-reference/#edgemiddleware)を有効にして、Netlify Edge Functionsでミドルウェアを実行します。
事前レンダリングされたページのリダイレクト、アクセス制御、またはカスタムレスポンスヘッダーを実装するには、[`middlewareMode`オプション](/ja/reference/adapter-reference/#middlewareMode)を有効にして、Netlify Edge Functionsでミドルウェアを実行します。

Check failure on line 103 in src/content/docs/ja/guides/integrations-guide/netlify.mdx

View workflow job for this annotation

GitHub Actions / Check Links

Broken fragment link in src/content/docs/ja/guides/integrations-guide/netlify.mdx, line 103: The linked page does not contain a fragment with the name "#middlewareMode". Available fragments: #theme-icons, #gradient, #starlight__sidebar, #__tab-スタート, #__tab-ガイド&レシピ, #__tab-リファレンス, #__tab-インテグレーション, #__tab-サードパーティ, #starlight__mobile-toc, #starlight__on-this-page--mobile, #starlight__on-this-page, #learn-astro-course-2, #_top, #what-is-an-adapter, #building-an-adapter, #name, #entrypointresolution, #serverentrypoint, #supportedastrofeatures, #adapterfeatures, #client, #internalfetchheaders, #assetqueryparams, #previewentrypoint, #args, #exports, #custom-prerenderer, #building-a-server-entrypoint, #passing-build-time-configuration, #astroappentrypoint, #createapp, #astroapp, #apprender, #renderoptions, #addcookieheader, #clientaddress, #locals, #prerenderederrorpagefetch, #routedata, #appmatch, #appgetadapterlogger, #appgetalloweddomains, #appremovebase, #appsetcookieheaders, #appgetsetcookiefromresponse, #appvalidateforwardedhost, #appsanitizehost, #appvalidateforwardedheaders, #astroappnode, #createrequest, #writeresponse, #astro-features, #staticoutput, #hybridoutput, #serveroutput, #i18ndomains, #envgetsecret, #sharpimageservice, #adapter-features, #middlewaremode, #buildoutput, #staticheaders, #adapter-types-reference, #adaptersupport, #adaptersupportskind, #adaptersupportwithmessage, #support, #message, #suppress, #middlewaremode-1, #allow-installation-via-astro-add, #docsearch-lvl0, #learn-astro-course-1

```js title="astro.config.mjs" ins={7}
import { defineConfig } from 'astro/config';
Expand Down
Loading