feat: middleware for several adapters

.changeset/brave-trains-hang.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/adapter-vercel': minor
+---
+
+feat: support edge middleware

.changeset/eleven-snakes-vanish.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/adapter-node': minor
+---
+
+feat: add possibility for adding polka/express middleware

.changeset/famous-boats-enjoy.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/kit': minor
+---
+
+feat: allow adapters to influence compilation entry points and to intercept requests at dev/preview time

.changeset/nice-tools-marry.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/adapter-vercel': minor
+---
+
+feat: add possibility of defining edge middleware

.changeset/tasty-shirts-shout.md

@@ -0,0 +1,5 @@
+---
+'@sveltejs/adapter-cloudflare': minor
+---
+
+feat: add pages-like middleware

documentation/docs/25-build-and-deploy/40-adapter-node.md

@@ -137,6 +137,54 @@ The number of seconds to wait before forcefully closing any remaining connection
 
 When using systemd socket activation, `IDLE_TIMEOUT` specifies the number of seconds after which the app is automatically put to sleep when receiving no requests. If not set, the app runs continuously. See [Socket activation](#Socket-activation) for more details.
 
+## Middleware
+
+You can integrate Express or Polka middleware into your SvelteKit application built with the Node adapter by placing a `node-middleware.js` file at the root of your project. It must export a default function which receives the same arguments as [Polka middleware](https://github.com/lukeed/polka?tab=readme-ov-file#middleware). The middleware runs on all requests. Combined with using [server-side route resolution](configuration#router) you can make sure it runs prior to all navigations, no matter prerendered or not and no matter client- or server-side.
+
+```js
+/// file: node-middleware.js
+// @filename: ambient.d.ts
+declare module 'polka';
+
+// @filename: index.js
+// ---cut---
+
+/**
+ * @param {import('polka').Request} req
+ * @param {import('polka').Response} res
+ * @param {import('polka').NextHandler} next
+ */
+export default function middleware(req, res, next) {
+	if (req.url !== '/') return next();
+
+	// Retrieve feature flag from cookies
+	let flag = split_cookies(req.headers.cookie ?? '')?.flag;
+
+	// Fall back to random value if this is a new visitor
+	flag ||= Math.random() > 0.5 ? 'a' : 'b';
+
+	// Get destination URL based on the feature flag
+	req.url = flag === 'a' ? '/home-a' : '/home-b';
+
+	// Set a cookie to remember the feature flags for this visitor
+	res.appendHeader('Set-Cookie', `flag=${flag}; Path=/`);
+
+	return next();
+}
+
+/** @param {string} cookies */
+function split_cookies(cookies) {
+	return cookies.split(';').reduce(
+		(acc, cookie) => {
+			const [name, value] = cookie.trim().split('=');
+			acc[name] = value;
+			return acc;
+		},
+		{} as Record<string, string>
+	);
+}
+```
+
 ## Options
 
 The adapter can be configured with various options:

documentation/docs/25-build-and-deploy/60-adapter-cloudflare.md

@@ -107,6 +107,70 @@ Cloudflare Workers specific values in the `platform` property are emulated durin
 
 For testing the build, you should use [Wrangler](https://developers.cloudflare.com/workers/wrangler/) **version 3**. Once you have built your site, run `wrangler pages dev .svelte-kit/cloudflare`.
 
+## Pages Middleware
+
+You can deploy one middleware function that closely follows the [Pages Middleware API](https://developers.cloudflare.com/pages/functions/middleware/). You can use it to intercept requests even for prerendered pages. Combined with using [server-side route resolution](configuration#router) you can make sure it runs prior to all navigations, no matter client- or server-side. This allows you to for example run A/B-tests on prerendered pages by rerouting a user to either variant A or B depending on a cookie.
+
+> [!NOTE] It isn't really Pages Middleware because the adapter compiles to a [single `_worker.js` file](https://developers.cloudflare.com/pages/platform/functions/#advanced-mode) (also see the [Notes](#Notes) section), which ignores middleware, but it closely mirrors its capabilities.
+
+To get started, place a `cloudflare-middleware.js` file at the root of your project and export a `onRequest` function from it:
+
+```js
+/// file: cloudflare-middleware.js
+// @filename: ambient.d.ts
+declare module '@cloudflare/workers-types';
+
+// @filename: index.js
+// ---cut---
+import { normalizeUrl } from '@sveltejs/kit';
+
+/**
+ * @param {import('@cloudflare/workers-types'.EventContext)} context
+ */
+export function onRequest({ request, next }) {
+	const url = new URL(request.url);
+
+	if (url.pathname !== '/') return next();
+
+	// Retrieve cookies which contain the feature flags.
+	let flag = split_cookies(request.headers.get('cookie') ?? '')?.['flags'];
+
+	// Fall back to random value if this is a new visitor
+	flag ||= Math.random() > 0.5 ? 'a' : 'b';
+
+	// Get destination URL based on the feature flag
+	request = new Request(new URL(flag === 'a' ? '/home-a' : '/home-b', url), request);
+
+	const response = await next(request);
+
+	// Set a cookie to remember the feature flags for this visitor
+	response.headers.set('Set-Cookie', `flags=${flag}; Path=/`);
+
+	return response;
+}
+
+/** @param {string} cookies */
+function split_cookies(cookies) {
+	return cookies.split(';').reduce(
+		(acc, cookie) => {
+			const [name, value] = cookie.trim().split('=');
+			acc[name] = value;
+			return acc;
+		},
+		{} as Record<string, string>
+	);
+}
+
+```
+
+The `context` parameter closely follows the [EventContext](https://developers.cloudflare.com/pages/functions/api-reference/#eventcontext) object but is missing some Pages-specific parameters such as `data`, `params` and `functionPath`.
+
+The middleware runs on all requests that your worker is invoked for, which is dependent on the [`include/exlcude` options](#Options-routes).
+
+> [!NOTE] Locally during dev and preview this only approximates the capabilities of middleware. Notably, you cannot read the request or response body, and middleware runs on all requests except those that would end up in `_app/immutable`.
+
+> [!NOTE] If you want to run code prior to a request but neither have prerendered pages nor rerouting logic, then it makes more sense to use the [handle hook](hooks#Server-hooks-handle) instead.
+
 ## Notes
 
 Functions contained in the [`/functions` directory](https://developers.cloudflare.com/pages/functions/routing/) at the project's root will _not_ be included in the deployment. Instead, functions should be implemented as [server endpoints](routing#server) in your SvelteKit app, which is compiled to a [single `_worker.js` file](https://developers.cloudflare.com/pages/functions/advanced-mode/).

documentation/docs/25-build-and-deploy/80-adapter-netlify.md

@@ -66,6 +66,48 @@ export default {
 };
 ```
 
+## Edge Middleware
+
+You can deploy one Netlify Edge Function [as middleware](https://docs.netlify.com/edge-functions/api/#modify-a-response) by placing an `edge-middleware.js` file at the root of your project. You can use it to intercept requests even for prerendered pages. Combined with using [server-side route resolution](configuration#router) you can make sure it runs prior to all navigations, no matter client- or server-side. This allows you to for example run A/B-tests on prerendered pages by rerouting a user to either variant A or B depending on a cookie.
+
+```js
+/// file: edge-middleware.js
+// @filename: ambient.d.ts
+declare module '@netlify/edge-functions';
+
+// @filename: index.js
+// ---cut---
+import { normalizeUrl } from '@sveltejs/kit';
+
+/**
+ * @param {Request} request
+ * @param {import('@netlify/edge-functions').Context} context
+ */
+export default async function middleware(request, { next, cookies }) {
+	const url = new URL(request.url);
+
+	if (url.pathname !== '/') return next();
+
+	// Retrieve feature flag from cookies
+	let flag = cookies.get('flag');
+
+	// Fall back to random value if this is a new visitor
+	flag ||= Math.random() > 0.5 ? 'a' : 'b';
+
+	// Set a cookie to remember the feature flags for this visitor
+	cookies.set('flag', flag);
+
+	// Get destination URL based on the feature flag
+	return new URL(flag === 'a' ? '/home-a' : '/home-b', url);
+}
+```
+
+By default middleware runs on all requests except for files within `_app/`. You can customize this by exporting a `export const config = { pattern: '<regex string>' }` object from the file similar to [how you can do it for native edge functions](https://docs.netlify.com/edge-functions/declarations/#declare-edge-functions-inline).
+
+> [!NOTE] Locally during dev and preview this only approximates the capabilities of edge functions. Notably, you cannot read the request or response body, and many properties on the context object are `null`ed.
+
+> [!NOTE] If you want to run code prior to a request but neither have prerendered pages nor rerouting logic, then it makes more sense to use the [handle hook](hooks#Server-hooks-handle) instead.
+
 ## Netlify alternatives to SvelteKit functionality
 
 You may build your app using functionality provided directly by SvelteKit without relying on any Netlify functionality. Using the SvelteKit versions of these features will allow them to be used in dev mode, tested with integration tests, and to work with other adapters should you ever decide to switch away from Netlify. However, in some scenarios you may find it beneficial to use the Netlify versions of these features. One example would be if you're migrating an app that's already hosted on Netlify to SvelteKit.

documentation/docs/25-build-and-deploy/90-adapter-vercel.md

@@ -90,7 +90,7 @@ export default {
 
 Vercel supports [Incremental Static Regeneration](https://vercel.com/docs/incremental-static-regeneration) (ISR), which provides the performance and cost advantages of prerendered content with the flexibility of dynamically rendered content.
 
-> Use ISR only on routes where every visitor should see the same content (much like when you prerender). If there's anything user-specific happening (like session cookies), they should happen on the client via JavaScript only to not leak sensitive information across visits
+> [!NOTE] Use ISR only on routes where every visitor should see the same content (much like when you prerender). If there's anything user-specific happening (like session cookies), they should happen on the client via JavaScript only to not leak sensitive information across visits
 
 To add ISR to a route, include the `isr` property in your `config` object:
 
@@ -107,7 +107,7 @@ export const config = {
 };
 ```
 
-> Using ISR on a route with `export const prerender = true` will have no effect, since the route is prerendered at build time
+> [!NOTE] Using ISR on a route with `export const prerender = true` will have no effect, since the route is prerendered at build time
 
 The `expiration` property is required; all others are optional. The properties are discussed in more detail below.
 
@@ -139,7 +139,63 @@ vercel env pull .env.development.local
 
 A list of valid query parameters that contribute to the cache key. Other parameters (such as utm tracking codes) will be ignored, ensuring that they do not result in content being re-generated unnecessarily. By default, query parameters are ignored.
 
-> Pages that are  [prerendered](page-options#prerender) will ignore ISR configuration.
+> [!NOTE] Pages that are  [prerendered](page-options#prerender) will ignore ISR configuration.
+
+## Edge Middleware
+
+You can make use of [Vercel Edge Middleware](https://vercel.com/docs/functions/edge-middleware) by placing an `edge-middleware.js` file at the root of your project. You can use it to intercept requests even for prerendered or ISR'd pages. Combined with using [server-side route resolution](configuration#router) you can make sure it runs prior to all navigations, no matter client- or server-side. This allows you to for example run A/B-tests on prerendered or ISR'd pages by rerouting a user to either variant A or B depending on a cookie.
+
+```js
+/// file: edge-middleware.js
+// @filename: ambient.d.ts
+declare module '@vercel/edge';
+
+// @filename: index.js
+// ---cut---
+import { rewrite, next } from '@vercel/edge';
+
+/**
+ * @param {Request} request
+ */
+export default async function middleware(request) {
+	const url = new URL(request.url);
+
+	if (url.pathname !== '/') return next();
+
+	// Retrieve feature flag from cookies
+	let flag = split_cookies(request.headers.get('cookie') ?? '')?.flag;
+
+	// Fall back to random value if this is a new visitor
+	flag ||= Math.random() > 0.5 ? 'a' : 'b';
+
+	return rewrite(
+		// Get destination URL based on the feature flag
+		flag === 'a' ? '/home-a' : '/home-b',
+		{
+			headers: {
+				// Set a cookie to remember the feature flags for this visitor
+				'Set-Cookie': `flag=${flag}; Path=/`
+			}
+		}
+	);
+}
+
+/** @param {string} cookies */
+function split_cookies(cookies) {
+	return cookies.split(';').reduce(
+		(acc, cookie) => {
+			const [name, value] = cookie.trim().split('=');
+			acc[name] = value;
+			return acc;
+		},
+		{} as Record<string, string>
+	);
+}
+```
+
+By default, middleware runs on all requests except for files within `_app/immutable`. You can customize this by exporting a `config` object with a `matcher` property as described in Vercel's [API documentation](https://vercel.com/docs/functions/edge-middleware/middleware-api#match-paths-based-on-custom-matcher-config).
+
+> [!NOTE] If you want to run code prior to a request but neither have prerendered nor ISR'd pages and have no rerouting logic, then it makes more sense to use the [handle hook](hooks#Server-hooks-handle) instead.
 
 ## Environment variables
 

documentation/docs/25-build-and-deploy/99-writing-adapters.md

@@ -21,11 +21,18 @@ export default function (options) {
 		async adapt(builder) {
 			// adapter implementation
 		},
-		async emulate() {
+		async emulate({ importEntryPoint }) {
 			return {
 				async platform({ config, prerender }) {
 					// the returned object becomes `event.platform` during dev, build and
 					// preview. Its shape is that of `App.Platform`
+				},
+				async interceptRequest(req, res, next) {
+					// Allows you to run code before a request to a prerendered page, a static asset,
+					// or a regular request to the SvelteKit runtime, both in dev and preview mode.
+					// Allows you to for example replicate middleware during dev and preview.
+					const module = await importEntryPoint('additional-entry-point');
+					module.default(req, res, next);
 				}
 			}
 		},
@@ -35,6 +42,12 @@ export default function (options) {
 				// from `$app/server` in production, return `false` if it can't.
 				// Or throw a descriptive error describing how to configure the deployment
 			}
+		},
+		// Allows you to configure additional entry points for compilation.
+		// You can use these via `importEntryPoint` within `emulate` and reference them
+		// from `${builder.getServerDirectory()}/adapter/<name>.js` for further compilation/bundling.
+		additionalEntryPoints: {
+			'additional-entry-point': 'my-project-root-relative-file.js'
 		}
 	};