Merge branch 'main' into feat/middleware-new-apis-plt-578

.github/PULL_REQUEST_TEMPLATE.md

@@ -15,6 +15,10 @@
 - What does this PR change? Give us a brief description.
 - Did you change something visual? A before/after screenshot can be helpful.
 
+<!-- Are these docs for an upcoming Astro release? -->
+<!-- Uncomment the line below and fill in the future Astro version and link the relevant `withastro/astro` PR.  -->
+<!-- #### For Astro version: `version`. See [Astro PR #](url). -->
+
 <!--
 Here’s what will happen next:
 

contributor-guides/astro-maintainers-guide-to-docs.md

@@ -137,15 +137,23 @@ Maintainers who submit PRs are expected to **merge their own PRs**, but only **a
 
 Typically, this will be an approval from another maintainer, often the Docs Lead or Docs Infrastructure Lead. But, in the case of minor PRs (e.g. typo fixes, broken links, etc.), any second LGTM is acceptable.
 
-Lastly, we have a "DocsBot" that posts congratulation messages in the #docs Discord channel. **Our bot also acknowledges co-authors!** During "Squash and Merge," if you would like to acknowledge any reviewer, please type in the exact phrase `Co-authored-by:` and include any missing reviewers or contributors whom you'd like to acknowledge!
+### `Co-authored-by:` credit
 
-### Getting `Co-Authored-by` Commit Message Name and Email
+We have a "DocsBot" that posts congratulation messages in the #docs Discord channel. **Our bot also acknowledges co-authors!** During "Squash and Merge," if you would like to acknowledge any reviewer, please type in the exact phrase `Co-authored-by:` and include any missing reviewers or contributors whom you'd like to acknowledge! For example:
 
-For the bot to work properly, you must use the exact co-author's name and email associated with their GitHub account. 
+```
+Co-authored-by: Sarah Rainsberger <[email protected]>
+Co-authored-by: Chris Swithinbank <[email protected]>
+Co-authored-by: Yan Thomas <[email protected]>
+Co-authored-by: Hippo <[email protected]>
+Co-authored-by: Kevin Zuniga Cuellar <[email protected]>
+Co-authored-by: ElianCodes <[email protected]>
+Co-authored-by: Reuben Tier <[email protected]>
+```
 
-You can look up that information using a GitHub commit they have made from any PR, even one from another repository! Please don't hesitate to take the extra step and include others!
+You must use the exact co-author's name and email associated with their GitHub account. You can look up that information using a GitHub commit they have made from any PR, even one from another repository! Please don't hesitate to take the extra step and include others!
 
-From an individual's commit, say `https://github.com/withastro/docs/commit/de11f2f2abf7ef54c874ebe0c85301d9bad36094`, add `.patch` to the end of the URL.
+From an individual's commit, e.g. `https://github.com/withastro/docs/commit/de11f2f2abf7ef54c874ebe0c85301d9bad36094`, add `.patch` to the end of the URL.
 
 This will bring up a "patchfile" containing all of the information about the commit, including the author's name and email address associated with the commit. You'll find this information in a field labelled `From:`.
 

src/content/docs/en/core-concepts/routing.mdx

@@ -321,7 +321,7 @@ Given the example above, here are a few examples of how the rules will match a r
 - `pages/posts/[pid].astro` - Will build `/posts/1`, `/posts/abc`, etc. But not `/posts/create`
 - `pages/posts/[...slug].astro` - Will build `/posts/1/2`, `/posts/a/b/c`, etc. But not `/posts/create`, `/posts/1`, `/posts/abc`
 
-Redirects also follow the same rules, but are prioritized *last*; if there is a file-based route and a redirect with the same route rule, the file-based route is chosen.
+Redirects also follow the same rules, but are prioritized *last*; if there is a file-based route and a redirect with the same route priority level, the file-based route is chosen.
 
 ## Pagination
 

src/content/docs/en/guides/integrations-guide/vercel.mdx

@@ -249,9 +249,9 @@ export default defineConfig({
 });
 ```
 
-### Vercel Middleware
+### Vercel Edge Middleware
 
-You can use Vercel middleware to intercept a request and redirect before sending a response. Vercel middleware can run for Edge, SSR, and Static deployments. You don't need to install `@vercel/edge` to write middleware, but you do need to install it to use features such as geolocation. For more information see [Vercel’s middleware documentation](https://vercel.com/docs/concepts/functions/edge-middleware).
+You can use Vercel Edge middleware to intercept a request and redirect before sending a response. Vercel middleware can run for Edge, SSR, and Static deployments. You may not need to install this package for your middleware. `@vercel/edge` is only required to use some middleware features such as geolocation. For more information see [Vercel’s middleware documentation](https://vercel.com/docs/concepts/functions/edge-middleware).
 
 1.  Add a `middleware.js` file to the root of your project:
 
@@ -280,6 +280,77 @@ You can use Vercel middleware to intercept a request and redirect before sending
 **Trying to rewrite?** Currently rewriting a request with middleware only works for static files.
 :::
 
+### Vercel Edge Middleware with Astro middleware
+
+The `@astrojs/vercel/serverless` adapter can automatically create the Vercel Edge middleware from an Astro middleware in your code base.
+
+This is an opt-in feature, and the `build.excludeMiddleware` option needs to be set to `true`:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import vercel from '@astrojs/vercel';
+export default defineConfig({
+  output: 'server',
+  adapter: vercel(),
+  build: {
+    excludeMiddleware: true,
+  },
+});
+```
+
+Optionally, you can create a file recognized by the adapter named `vercel-edge-middleware.(js|ts)` in the [`srcDir`](/en/reference/configuration-reference/#srcdir) folder to create [`Astro.locals`](/en/reference/api-reference/#astrolocals).
+
+Typings requires the [`@vercel/edge`](https://www.npmjs.com/package/@vercel/edge) package.
+
+```js
+// src/vercel-edge-middleware.js
+/**
+ *
+ * @param options.request {Request}
+ * @param options.context {import("@vercel/edge").RequestContext}
+ * @returns {object}
+ */
+export default function ({ request, context }) {
+  // do something with request and context
+  return {
+    title: "Spider-man's blog",
+  };
+}
+```
+
+If you use TypeScript, you can type the function as follows:
+
+```ts
+// src/vercel-edge-middleware.ts
+import type { RequestContext } from '@vercel/edge';
+
+export default function ({ request, context }: { request: Request; context: RequestContext }) {
+  // do something with request and context
+  return {
+    title: "Spider-man's blog",
+  };
+}
+```
+
+The data returned by this function will be passed to Astro middleware.
+
+The function:
+
+*   must export a **default** function;
+*   must **return** an `object`;
+*   accepts an object with a `request` and `context` as properties;
+*   `request` is typed as [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request);
+*   `context` is typed as [`RequestContext`](https://vercel.com/docs/concepts/functions/edge-functions/vercel-edge-package#requestcontext);
+
+#### Limitations and constraints
+
+When you opt in to this feature, there are few constraints to note:
+
+*   The Vercel Edge middleware will always be the **first** function to receive the `Request` and the last function to receive `Response`. This an architectural constraint that follows the [boundaries set by Vercel](https://vercel.com/docs/concepts/functions/edge-middleware).
+*   Only `request` and `context` may be used to produce an `Astro.locals` object. Operations like redirects, etc. should be delegated to Astro middleware.
+*   `Astro.locals` **must be serializable**. Failing to do so will result in a **runtime error**. This means that you **cannot** store complex types like `Map`, `function`, `Set`, etc.
+
 ## Troubleshooting
 
 **A few known complex packages (example: [puppeteer](https://github.com/puppeteer/puppeteer)) do not support bundling and therefore will not work properly with this adapter.** By default, Vercel doesn't include npm installed files & packages from your project's `./node_modules` folder. To address this, the `@astrojs/vercel` adapter automatically bundles your final build output using `esbuild`.

src/content/docs/en/reference/configuration-reference.mdx

@@ -547,6 +547,28 @@ of the `src/pages` directory.
 ```
 
 
+### build.excludeMiddleware
+
+<p>
+
+**Type:** `boolean`<br />
+**Default:** {false}<br />
+<Since v="2.8.0" />
+</p>
+
+Defines whether or not any SSR middleware code will be bundled when built.
+
+When enabled, middleware code is not bundled and imported by all pages during the build. To instead execute and import middleware code manually, set `build.excludeMiddleware: true`:
+
+```js
+{
+  build: {
+    excludeMiddleware: true
+  }
+}
+```
+
+
 ## Server Options
 
 Customize the Astro dev server, used by both `astro dev` and `astro preview`.