diff --git a/src/content/docs/en/guides/authentication.mdx b/src/content/docs/en/guides/authentication.mdx index e467fb0fdc28a..27eaa3399a3ad 100644 --- a/src/content/docs/en/guides/authentication.mdx +++ b/src/content/docs/en/guides/authentication.mdx @@ -264,6 +264,7 @@ export const onRequest = clerkMiddleware((auth, context) => { ### Examples +- [Astro authentication starter template](https://github.com/withastro/astro/tree/latest/examples/auth) - [GitHub OAuth example in Astro](https://github.com/lucia-auth/example-astro-github-oauth) - [Google OAuth example in Astro](https://github.com/lucia-auth/example-astro-google-oauth) - [Email and password example with 2FA in Astro](https://github.com/lucia-auth/example-astro-email-password-2fa) diff --git a/src/content/docs/en/guides/integrations-guide/node.mdx b/src/content/docs/en/guides/integrations-guide/node.mdx index aab128b0774d8..db6894ca6bfd8 100644 --- a/src/content/docs/en/guides/integrations-guide/node.mdx +++ b/src/content/docs/en/guides/integrations-guide/node.mdx @@ -185,6 +185,18 @@ export default defineConfig({ }); ``` +### `middlewareMode` + +

+**Type:** `'classic' | 'on-request'`
+**Default:** `classic`
+ +

+ +By default, middleware is executed at build time for prerendered pages, and on request for static pages. In this configuration prerendering must be disabled for any pages that should run middleware that depends on the user context. A common use case is authentication, where the request cookies are checked, and the user is either allowed access or redirected. + +To be able to manage authentication while still benefiting from prerendering, you can switch `middlewareMode` to `on-request`. In this mode, all middleware runs when the user requests the page, prerendered or not. + ## Usage First, [performing a build](/en/guides/deploy/#building-your-site-locally). Depending on which `mode` selected (see above) follow the appropriate steps below: diff --git a/src/content/docs/en/guides/middleware.mdx b/src/content/docs/en/guides/middleware.mdx index 86ab9d566ac2d..9c1e1b585ea35 100644 --- a/src/content/docs/en/guides/middleware.mdx +++ b/src/content/docs/en/guides/middleware.mdx @@ -7,9 +7,7 @@ import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; import { Steps } from '@astrojs/starlight/components'; import Since from '~/components/Since.astro'; -**Middleware** allows you to intercept requests and responses and inject behaviors dynamically every time a page or endpoint is about to be rendered. This rendering occurs at build time for all prerendered pages, but occurs when the route is requested for pages rendered on demand, making [additional SSR features like cookies and headers](/en/guides/on-demand-rendering/#on-demand-rendering-features) available. - -Middleware also allows you to set and share request-specific information across endpoints and pages by mutating a `locals` object that is available in all Astro components and API endpoints. This object is available even when this middleware runs at build time. +**Middleware** allows you to intercept requests and responses and inject behaviors dynamically. It also allows you to set and share request-specific information across endpoints and pages by mutating a `locals` object that is available in all Astro components and API endpoints. This object is available even when this middleware runs at build time. ## Basic Usage @@ -98,6 +96,12 @@ const data = Astro.locals; The value of `locals` cannot be overridden at run time. Doing so would risk wiping out all the information stored by the user. Astro performs checks and will throw an error if `locals` are overridden. ::: +## Middleware modes + +The `middlewareMode` you choose impacts when and in what context the middleware is executed. By default, middleware runs when a page is rendered. That means that for prerendered pages, middleware will run during the build, and never again after. For on-demand pages in the same project, middleware will be ran on request, making [additional SSR features like cookies and headers](/en/guides/on-demand-rendering/#on-demand-rendering-features) available. + +Some adapters will offer alternative middleware modes. For more details, please refer to the documentation of your chosen adapter. + ## Example: redacting sensitive information The example below uses middleware to replace "PRIVATE INFO" with the word "REDACTED" to allow you to render modified HTML on your page: diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index 629e34251bd5f..fd43c91b1be51 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -698,6 +698,8 @@ Determines at which stage of the page lifecycle the middleware is executed, and 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. +In `on-request` mode, middleware runs when the page is requested from the server, regardless of whether it is prerendered or not. At build time, the middleware is skipped. + 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} @@ -1020,7 +1022,7 @@ export default function createIntegration() {

-**Type:** `"classic" | "edge"`
+**Type:** `"classic" | "edge" | "on-request"`