astro 2.3.4 → 2.4.0

package/dist/core/config/schema.d.ts

@@ -9,10 +9,12 @@ export declare const AstroConfigSchema: z.ZodObject<{
     srcDir: z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodString>>, URL, string | undefined>;
     publicDir: z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodString>>, URL, string | undefined>;
     outDir: z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodString>>, URL, string | undefined>;
+    cacheDir: z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodString>>, URL, string | undefined>;
     site: z.ZodOptional<z.ZodString>;
     base: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     trailingSlash: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"always">, z.ZodLiteral<"never">, z.ZodLiteral<"ignore">]>>>;
     output: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"static">, z.ZodLiteral<"server">]>>>;
+    scopedStyleStrategy: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"where">, z.ZodLiteral<"class">]>>>;
     adapter: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
         hooks: z.ZodDefault<z.ZodObject<{}, "passthrough", z.ZodTypeAny, {}, {}>>;
@@ -152,10 +154,16 @@ export declare const AstroConfigSchema: z.ZodObject<{
     vite: z.ZodDefault<z.ZodType<ViteUserConfig, z.ZodTypeDef, ViteUserConfig>>;
     experimental: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         assets: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        inlineStylesheets: z.ZodDefault<z.ZodOptional<z.ZodEnum<["always", "auto", "never"]>>>;
+        middleware: z.ZodDefault<z.ZodOptional<z.ZodOptional<z.ZodBoolean>>>;
     }, "strip", z.ZodTypeAny, {
         assets: boolean;
+        middleware: boolean;
+        inlineStylesheets: "never" | "always" | "auto";
     }, {
         assets?: boolean | undefined;
+        middleware?: boolean | undefined;
+        inlineStylesheets?: "never" | "always" | "auto" | undefined;
     }>>>;
     legacy: z.ZodDefault<z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>>;
 }, "strip", z.ZodTypeAny, {
@@ -184,6 +192,7 @@ export declare const AstroConfigSchema: z.ZodObject<{
     srcDir: URL;
     publicDir: URL;
     outDir: URL;
+    cacheDir: URL;
     trailingSlash: "never" | "always" | "ignore";
     server: {
         headers?: OutgoingHttpHeaders | undefined;
@@ -191,6 +200,7 @@ export declare const AstroConfigSchema: z.ZodObject<{
         host: string | boolean;
         port: number;
     };
+    scopedStyleStrategy: "where" | "class";
     integrations: {
         name: string;
         hooks: {};
@@ -212,6 +222,8 @@ export declare const AstroConfigSchema: z.ZodObject<{
     vite: ViteUserConfig;
     experimental: {
         assets: boolean;
+        middleware: boolean;
+        inlineStylesheets: "never" | "always" | "auto";
     };
     legacy: {};
 }, {
@@ -236,8 +248,10 @@ export declare const AstroConfigSchema: z.ZodObject<{
     srcDir?: string | undefined;
     publicDir?: string | undefined;
     outDir?: string | undefined;
+    cacheDir?: string | undefined;
     trailingSlash?: "never" | "always" | "ignore" | undefined;
     server?: unknown;
+    scopedStyleStrategy?: "where" | "class" | undefined;
     adapter?: {
         hooks?: {} | undefined;
         name: string;
@@ -260,6 +274,8 @@ export declare const AstroConfigSchema: z.ZodObject<{
     vite?: ViteUserConfig | undefined;
     experimental?: {
         assets?: boolean | undefined;
+        middleware?: boolean | undefined;
+        inlineStylesheets?: "never" | "always" | "auto" | undefined;
     } | undefined;
     legacy?: {} | undefined;
 }>;
@@ -316,6 +332,7 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
     }>>;
     output: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"static">, z.ZodLiteral<"server">]>>>;
     trailingSlash: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"always">, z.ZodLiteral<"never">, z.ZodLiteral<"ignore">]>>>;
+    scopedStyleStrategy: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"where">, z.ZodLiteral<"class">]>>>;
     adapter: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
         hooks: z.ZodDefault<z.ZodObject<{}, "passthrough", z.ZodTypeAny, {}, {}>>;
@@ -364,16 +381,23 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
     vite: z.ZodDefault<z.ZodType<ViteUserConfig, z.ZodTypeDef, ViteUserConfig>>;
     experimental: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         assets: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        inlineStylesheets: z.ZodDefault<z.ZodOptional<z.ZodEnum<["always", "auto", "never"]>>>;
+        middleware: z.ZodDefault<z.ZodOptional<z.ZodOptional<z.ZodBoolean>>>;
     }, "strip", z.ZodTypeAny, {
         assets: boolean;
+        middleware: boolean;
+        inlineStylesheets: "never" | "always" | "auto";
     }, {
         assets?: boolean | undefined;
+        middleware?: boolean | undefined;
+        inlineStylesheets?: "never" | "always" | "auto" | undefined;
     }>>>;
     legacy: z.ZodDefault<z.ZodOptional<z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>>>;
     root: z.ZodEffects<z.ZodDefault<z.ZodString>, URL, string | undefined>;
     srcDir: z.ZodEffects<z.ZodDefault<z.ZodString>, URL, string | undefined>;
     publicDir: z.ZodEffects<z.ZodDefault<z.ZodString>, URL, string | undefined>;
     outDir: z.ZodEffects<z.ZodDefault<z.ZodString>, URL, string | undefined>;
+    cacheDir: z.ZodEffects<z.ZodDefault<z.ZodString>, URL, string | undefined>;
     build: z.ZodDefault<z.ZodOptional<z.ZodObject<{
         format: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"file">, z.ZodLiteral<"directory">]>>>;
         client: z.ZodEffects<z.ZodDefault<z.ZodOptional<z.ZodString>>, URL, string | undefined>;
@@ -447,6 +471,7 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
     srcDir: URL;
     publicDir: URL;
     outDir: URL;
+    cacheDir: URL;
     trailingSlash: "never" | "always" | "ignore";
     server: {
         headers?: OutgoingHttpHeaders | undefined;
@@ -455,6 +480,7 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
         port: number;
         streaming: boolean;
     };
+    scopedStyleStrategy: "where" | "class";
     integrations: {
         name: string;
         hooks: {};
@@ -476,6 +502,8 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
     vite: ViteUserConfig;
     experimental: {
         assets: boolean;
+        middleware: boolean;
+        inlineStylesheets: "never" | "always" | "auto";
     };
     legacy: {};
 }, {
@@ -500,8 +528,10 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
     srcDir?: string | undefined;
     publicDir?: string | undefined;
     outDir?: string | undefined;
+    cacheDir?: string | undefined;
     trailingSlash?: "never" | "always" | "ignore" | undefined;
     server?: unknown;
+    scopedStyleStrategy?: "where" | "class" | undefined;
     adapter?: {
         hooks?: {} | undefined;
         name: string;
@@ -524,6 +554,8 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
     vite?: ViteUserConfig | undefined;
     experimental?: {
         assets?: boolean | undefined;
+        middleware?: boolean | undefined;
+        inlineStylesheets?: "never" | "always" | "auto" | undefined;
     } | undefined;
     legacy?: {} | undefined;
 }>, {
@@ -552,6 +584,7 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
     srcDir: URL;
     publicDir: URL;
     outDir: URL;
+    cacheDir: URL;
     trailingSlash: "never" | "always" | "ignore";
     server: {
         headers?: OutgoingHttpHeaders | undefined;
@@ -560,6 +593,7 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
         port: number;
         streaming: boolean;
     };
+    scopedStyleStrategy: "where" | "class";
     integrations: {
         name: string;
         hooks: {};
@@ -581,6 +615,8 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
     vite: ViteUserConfig;
     experimental: {
         assets: boolean;
+        middleware: boolean;
+        inlineStylesheets: "never" | "always" | "auto";
     };
     legacy: {};
 }, {
@@ -605,8 +641,10 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
     srcDir?: string | undefined;
     publicDir?: string | undefined;
     outDir?: string | undefined;
+    cacheDir?: string | undefined;
     trailingSlash?: "never" | "always" | "ignore" | undefined;
     server?: unknown;
+    scopedStyleStrategy?: "where" | "class" | undefined;
     adapter?: {
         hooks?: {} | undefined;
         name: string;
@@ -629,6 +667,8 @@ export declare function createRelativeSchema(cmd: string, fileProtocolRoot: URL)
     vite?: ViteUserConfig | undefined;
     experimental?: {
         assets?: boolean | undefined;
+        middleware?: boolean | undefined;
+        inlineStylesheets?: "never" | "always" | "auto" | undefined;
     } | undefined;
     legacy?: {} | undefined;
 }>;

package/dist/core/config/schema.js

@@ -7,6 +7,7 @@ const ASTRO_CONFIG_DEFAULTS = {
   srcDir: "./src",
   publicDir: "./public",
   outDir: "./dist",
+  cacheDir: "./node_modules/.astro",
   base: "/",
   trailingSlash: "ignore",
   build: {
@@ -30,7 +31,9 @@ const ASTRO_CONFIG_DEFAULTS = {
   vite: {},
   legacy: {},
   experimental: {
-    assets: false
+    assets: false,
+    inlineStylesheets: "never",
+    middleware: false
   }
 };
 const AstroConfigSchema = z.object({
@@ -38,10 +41,12 @@ const AstroConfigSchema = z.object({
   srcDir: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.srcDir).transform((val) => new URL(val)),
   publicDir: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.publicDir).transform((val) => new URL(val)),
   outDir: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.outDir).transform((val) => new URL(val)),
+  cacheDir: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.cacheDir).transform((val) => new URL(val)),
   site: z.string().url().optional(),
   base: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.base),
   trailingSlash: z.union([z.literal("always"), z.literal("never"), z.literal("ignore")]).optional().default(ASTRO_CONFIG_DEFAULTS.trailingSlash),
   output: z.union([z.literal("static"), z.literal("server")]).optional().default("static"),
+  scopedStyleStrategy: z.union([z.literal("where"), z.literal("class")]).optional().default("where"),
   adapter: z.object({ name: z.string(), hooks: z.object({}).passthrough().default({}) }).optional(),
   integrations: z.preprocess(
     // preprocess
@@ -108,7 +113,9 @@ const AstroConfigSchema = z.object({
   }).default({}),
   vite: z.custom((data) => data instanceof Object && !Array.isArray(data)).default(ASTRO_CONFIG_DEFAULTS.vite),
   experimental: z.object({
-    assets: z.boolean().optional().default(ASTRO_CONFIG_DEFAULTS.experimental.assets)
+    assets: z.boolean().optional().default(ASTRO_CONFIG_DEFAULTS.experimental.assets),
+    inlineStylesheets: z.enum(["always", "auto", "never"]).optional().default(ASTRO_CONFIG_DEFAULTS.experimental.inlineStylesheets),
+    middleware: z.oboolean().optional().default(ASTRO_CONFIG_DEFAULTS.experimental.middleware)
   }).optional().default({}),
   legacy: z.object({}).optional().default({})
 });
@@ -118,6 +125,7 @@ function createRelativeSchema(cmd, fileProtocolRoot) {
     srcDir: z.string().default(ASTRO_CONFIG_DEFAULTS.srcDir).transform((val) => new URL(appendForwardSlash(val), fileProtocolRoot)),
     publicDir: z.string().default(ASTRO_CONFIG_DEFAULTS.publicDir).transform((val) => new URL(appendForwardSlash(val), fileProtocolRoot)),
     outDir: z.string().default(ASTRO_CONFIG_DEFAULTS.outDir).transform((val) => new URL(appendForwardSlash(val), fileProtocolRoot)),
+    cacheDir: z.string().default(ASTRO_CONFIG_DEFAULTS.cacheDir).transform((val) => new URL(appendForwardSlash(val), fileProtocolRoot)),
     build: z.object({
       format: z.union([z.literal("file"), z.literal("directory")]).optional().default(ASTRO_CONFIG_DEFAULTS.build.format),
       client: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.build.client).transform((val) => new URL(val, fileProtocolRoot)),

package/dist/core/constants.d.ts

@@ -1,2 +1,3 @@
 export declare const ASTRO_VERSION: string;
 export declare const SUPPORTED_MARKDOWN_FILE_EXTENSIONS: readonly [".markdown", ".mdown", ".mkdn", ".mkd", ".mdwn", ".md"];
+export declare const MIDDLEWARE_PATH_SEGMENT_NAME = "middleware";

package/dist/core/constants.js

@@ -1,4 +1,4 @@
-const ASTRO_VERSION = "2.3.4";
+const ASTRO_VERSION = "2.4.0";
 const SUPPORTED_MARKDOWN_FILE_EXTENSIONS = [
   ".markdown",
   ".mdown",
@@ -7,7 +7,9 @@ const SUPPORTED_MARKDOWN_FILE_EXTENSIONS = [
   ".mdwn",
   ".md"
 ];
+const MIDDLEWARE_PATH_SEGMENT_NAME = "middleware";
 export {
   ASTRO_VERSION,
+  MIDDLEWARE_PATH_SEGMENT_NAME,
   SUPPORTED_MARKDOWN_FILE_EXTENSIONS
 };

package/dist/core/dev/dev.js

@@ -53,7 +53,7 @@ async function dev(settings, options) {
       isRestart: options.isRestart
     })
   );
-  const currentVersion = "2.3.4";
+  const currentVersion = "2.4.0";
   if (currentVersion.includes("-")) {
     warn(options.logging, null, msg.prerelease({ currentVersion }));
   }

package/dist/core/endpoint/dev/index.js

@@ -3,16 +3,19 @@ import { call as callEndpoint } from "../index.js";
 async function call(options, logging) {
   const {
     env,
-    preload: [, mod]
+    preload: [, mod],
+    middleware
   } = options;
   const endpointHandler = mod;
-  const ctx = createRenderContext({
+  const ctx = await createRenderContext({
     request: options.request,
     origin: options.origin,
     pathname: options.pathname,
-    route: options.route
+    route: options.route,
+    env,
+    mod: endpointHandler
   });
-  return await callEndpoint(endpointHandler, env, ctx, logging);
+  return await callEndpoint(endpointHandler, env, ctx, logging, middleware);
 }
 export {
   call

package/dist/core/endpoint/index.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-import type { AstroConfig, EndpointHandler } from '../../@types/astro';
+import type { APIContext, AstroConfig, AstroMiddlewareInstance, EndpointHandler, EndpointOutput, Params } from '../../@types/astro';
 import type { Environment, RenderContext } from '../render/index';
 import { AstroCookies } from '../cookies/index.js';
 import { type LogOptions } from '../logger/core.js';
@@ -12,6 +12,13 @@ type EndpointCallResult = {
     type: 'response';
     response: Response;
 };
-export declare function call(mod: EndpointHandler, env: Environment, ctx: RenderContext, logging: LogOptions): Promise<EndpointCallResult>;
+export declare function createAPIContext({ request, params, site, props, adapterName, }: {
+    request: Request;
+    params: Params;
+    site?: string;
+    props: Record<string, any>;
+    adapterName?: string;
+}): APIContext;
+export declare function call<MiddlewareResult = Response | EndpointOutput>(mod: EndpointHandler, env: Environment, ctx: RenderContext, logging: LogOptions, middleware?: AstroMiddlewareInstance<MiddlewareResult> | undefined): Promise<EndpointCallResult>;
 export declare function throwIfRedirectNotAllowed(response: Response, config: AstroConfig): void;
 export {};

package/dist/core/endpoint/index.js

@@ -3,8 +3,10 @@ import { ASTRO_VERSION } from "../constants.js";
 import { AstroCookies, attachToResponse } from "../cookies/index.js";
 import { AstroError, AstroErrorData } from "../errors/index.js";
 import { warn } from "../logger/core.js";
-import { getParamsAndProps, GetParamsAndPropsError } from "../render/core.js";
+import { callMiddleware } from "../middleware/callMiddleware.js";
+import { isValueSerializable } from "../render/core.js";
 const clientAddressSymbol = Symbol.for("astro.clientAddress");
+const clientLocalsSymbol = Symbol.for("astro.locals");
 function createAPIContext({
   request,
   params,
@@ -12,7 +14,7 @@ function createAPIContext({
   props,
   adapterName
 }) {
-  return {
+  const context = {
     cookies: new AstroCookies(request),
     request,
     params,
@@ -28,7 +30,6 @@ function createAPIContext({
       });
     },
     url: new URL(request.url),
-    // @ts-expect-error
     get clientAddress() {
       if (!(clientAddressSymbol in request)) {
         if (adapterName) {
@@ -43,33 +44,49 @@ function createAPIContext({
       return Reflect.get(request, clientAddressSymbol);
     }
   };
-}
-async function call(mod, env, ctx, logging) {
-  var _a, _b;
-  const paramsAndPropsResp = await getParamsAndProps({
-    mod,
-    route: ctx.route,
-    routeCache: env.routeCache,
-    pathname: ctx.pathname,
-    logging: env.logging,
-    ssr: env.ssr
+  Object.defineProperty(context, "locals", {
+    get() {
+      return Reflect.get(request, clientLocalsSymbol);
+    },
+    set(val) {
+      if (typeof val !== "object") {
+        throw new AstroError(AstroErrorData.LocalsNotAnObject);
+      } else {
+        Reflect.set(request, clientLocalsSymbol, val);
+      }
+    }
   });
-  if (paramsAndPropsResp === GetParamsAndPropsError.NoMatchingStaticPath) {
-    throw new AstroError({
-      ...AstroErrorData.NoMatchingStaticPathFound,
-      message: AstroErrorData.NoMatchingStaticPathFound.message(ctx.pathname),
-      hint: ((_a = ctx.route) == null ? void 0 : _a.component) ? AstroErrorData.NoMatchingStaticPathFound.hint([(_b = ctx.route) == null ? void 0 : _b.component]) : ""
-    });
-  }
-  const [params, props] = paramsAndPropsResp;
+  return context;
+}
+async function call(mod, env, ctx, logging, middleware) {
   const context = createAPIContext({
     request: ctx.request,
-    params,
-    props,
+    params: ctx.params,
+    props: ctx.props,
     site: env.site,
     adapterName: env.adapterName
   });
-  const response = await renderEndpoint(mod, context, env.ssr);
+  let response = await renderEndpoint(mod, context, env.ssr);
+  if (middleware && middleware.onRequest) {
+    if (response.body === null) {
+      const onRequest = middleware.onRequest;
+      response = await callMiddleware(onRequest, context, async () => {
+        if (env.mode === "development" && !isValueSerializable(context.locals)) {
+          throw new AstroError({
+            ...AstroErrorData.LocalsNotSerializable,
+            message: AstroErrorData.LocalsNotSerializable.message(ctx.pathname)
+          });
+        }
+        return response;
+      });
+    } else {
+      warn(
+        env.logging,
+        "middleware",
+        "Middleware doesn't work for endpoints that return a simple body. The middleware will be disabled for this page."
+      );
+    }
+  }
   if (response instanceof Response) {
     attachToResponse(response, context.cookies);
     return {
@@ -110,5 +127,6 @@ function throwIfRedirectNotAllowed(response, config) {
 }
 export {
   call,
+  createAPIContext,
   throwIfRedirectNotAllowed
 };

package/dist/core/errors/errors-data.d.ts

@@ -555,6 +555,87 @@ export declare const AstroErrorData: {
         readonly code: 3030;
         readonly message: "The response has already been sent to the browser and cannot be altered.";
     };
+    /**
+     * @docs
+     * @description
+     * Thrown when the middleware does not return any data or call the `next` function.
+     *
+     * For example:
+     * ```ts
+     * import {defineMiddleware} from "astro/middleware";
+     * export const onRequest = defineMiddleware((context, _) => {
+     * 	// doesn't return anything or call `next`
+     * 	context.locals.someData = false;
+     * });
+     * ```
+     */
+    readonly MiddlewareNoDataOrNextCalled: {
+        readonly title: "The middleware didn't return a response or call `next`";
+        readonly code: 3031;
+        readonly message: "The middleware needs to either return a `Response` object or call the `next` function.";
+    };
+    /**
+     * @docs
+     * @description
+     * Thrown in development mode when middleware returns something that is not a `Response` object.
+     *
+     * For example:
+     * ```ts
+     * import {defineMiddleware} from "astro/middleware";
+     * export const onRequest = defineMiddleware(() => {
+     *   return "string"
+     * });
+     * ```
+     */
+    readonly MiddlewareNotAResponse: {
+        readonly title: "The middleware returned something that is not a `Response` object";
+        readonly code: 3032;
+        readonly message: "Any data returned from middleware must be a valid `Response` object.";
+    };
+    /**
+     * @docs
+     * @description
+     *
+     * Thrown in development mode when `locals` is overwritten with something that is not an object
+     *
+     * For example:
+     * ```ts
+     * import {defineMiddleware} from "astro/middleware";
+     * export const onRequest = defineMiddleware((context, next) => {
+     *   context.locals = 1541;
+     *   return next();
+     * });
+     * ```
+     */
+    readonly LocalsNotAnObject: {
+        readonly title: "Value assigned to `locals` is not accepted";
+        readonly code: 3033;
+        readonly message: "`locals` can only be assigned to an object. Other values like numbers, strings, etc. are not accepted.";
+        readonly hint: "If you tried to remove some information from the `locals` object, try to use `delete` or set the property to `undefined`.";
+    };
+    /**
+     * @docs
+     * @description
+     * Thrown in development mode when a user attempts to store something that is not serializable in `locals`.
+     *
+     * For example:
+     * ```ts
+     * import {defineMiddleware} from "astro/middleware";
+     * export const onRequest = defineMiddleware((context, next) => {
+     *   context.locals = {
+     *     foo() {
+     *       alert("Hello world!")
+     *     }
+     *   };
+     *   return next();
+     * });
+     * ```
+     */
+    readonly LocalsNotSerializable: {
+        readonly title: "`Astro.locals` is not serializable";
+        readonly code: 3034;
+        readonly message: (href: string) => string;
+    };
     /**
      * @docs
      * @see

package/dist/core/errors/errors-data.js

@@ -568,6 +568,90 @@ Expected \`true\` value but got \`${suffix}\`.`;
     code: 3030,
     message: "The response has already been sent to the browser and cannot be altered."
   },
+  /**
+   * @docs
+   * @description
+   * Thrown when the middleware does not return any data or call the `next` function.
+   *
+   * For example:
+   * ```ts
+   * import {defineMiddleware} from "astro/middleware";
+   * export const onRequest = defineMiddleware((context, _) => {
+   * 	// doesn't return anything or call `next`
+   * 	context.locals.someData = false;
+   * });
+   * ```
+   */
+  MiddlewareNoDataOrNextCalled: {
+    title: "The middleware didn't return a response or call `next`",
+    code: 3031,
+    message: "The middleware needs to either return a `Response` object or call the `next` function."
+  },
+  /**
+   * @docs
+   * @description
+   * Thrown in development mode when middleware returns something that is not a `Response` object.
+   *
+   * For example:
+   * ```ts
+   * import {defineMiddleware} from "astro/middleware";
+   * export const onRequest = defineMiddleware(() => {
+   *   return "string"
+   * });
+   * ```
+   */
+  MiddlewareNotAResponse: {
+    title: "The middleware returned something that is not a `Response` object",
+    code: 3032,
+    message: "Any data returned from middleware must be a valid `Response` object."
+  },
+  /**
+   * @docs
+   * @description
+   *
+   * Thrown in development mode when `locals` is overwritten with something that is not an object
+   *
+   * For example:
+   * ```ts
+   * import {defineMiddleware} from "astro/middleware";
+   * export const onRequest = defineMiddleware((context, next) => {
+   *   context.locals = 1541;
+   *   return next();
+   * });
+   * ```
+   */
+  LocalsNotAnObject: {
+    title: "Value assigned to `locals` is not accepted",
+    code: 3033,
+    message: "`locals` can only be assigned to an object. Other values like numbers, strings, etc. are not accepted.",
+    hint: "If you tried to remove some information from the `locals` object, try to use `delete` or set the property to `undefined`."
+  },
+  /**
+   * @docs
+   * @description
+   * Thrown in development mode when a user attempts to store something that is not serializable in `locals`.
+   *
+   * For example:
+   * ```ts
+   * import {defineMiddleware} from "astro/middleware";
+   * export const onRequest = defineMiddleware((context, next) => {
+   *   context.locals = {
+   *     foo() {
+   *       alert("Hello world!")
+   *     }
+   *   };
+   *   return next();
+   * });
+   * ```
+   */
+  LocalsNotSerializable: {
+    title: "`Astro.locals` is not serializable",
+    code: 3034,
+    message: (href) => {
+      return `The information stored in \`Astro.locals\` for the path "${href}" is not serializable.
+Make sure you store only serializable data.`;
+    }
+  },
   // No headings here, that way Vite errors are merged with Astro ones in the docs, which makes more sense to users.
   // Vite Errors - 4xxx
   /**

package/dist/core/messages.js

@@ -47,7 +47,7 @@ function serverStart({
   base,
   isRestart = false
 }) {
-  const version = "2.3.4";
+  const version = "2.4.0";
   const localPrefix = `${dim("\u2503")} Local    `;
   const networkPrefix = `${dim("\u2503")} Network  `;
   const emptyPrefix = " ".repeat(11);
@@ -233,7 +233,7 @@ function printHelp({
     message.push(
       linebreak(),
       `  ${bgGreen(black(` ${commandName} `))} ${green(
-        `v${"2.3.4"}`
+        `v${"2.4.0"}`
       )} ${headline}`
     );
   }

package/dist/core/middleware/callMiddleware.d.ts

@@ -0,0 +1,36 @@
+import type { APIContext, MiddlewareHandler } from '../../@types/astro';
+/**
+ * Utility function that is in charge of calling the middleware.
+ *
+ * It accepts a `R` generic, which usually is the `Response` returned.
+ * It is a generic because endpoints can return a different payload.
+ *
+ * When calling a middleware, we provide a `next` function, this function might or
+ * might not be called.
+ *
+ * A middleware, to behave correctly, can:
+ * - return a `Response`;
+ * - call `next`;
+ *
+ * Failing doing so will result an error. A middleware can call `next` and do not return a
+ * response. A middleware can not call `next` and return a new `Response` from scratch (maybe with a redirect).
+ *
+ * ```js
+ * const onRequest = async (context, next) => {
+ *   const response = await next(context);
+ *   return response;
+ * }
+ * ```
+ *
+ * ```js
+ * const onRequest = async (context, next) => {
+ *   context.locals = "foo";
+ *   next();
+ * }
+ * ```
+ *
+ * @param onRequest The function called which accepts a `context` and a `resolve` function
+ * @param apiContext The API context
+ * @param responseFunction A callback function that should return a promise with the response
+ */
+export declare function callMiddleware<R>(onRequest: MiddlewareHandler<R>, apiContext: APIContext, responseFunction: () => Promise<R>): Promise<Response | R>;