feat(logger): docs and runtime

.changeset/silver-berries-send.md

@@ -0,0 +1,58 @@
+---
+'astro': minor
+---
+
+Adds a new experimental logger, which allows to provide better controls over Astro's logging infrastructure.
+
+#### JSON logging
+
+JSON logging can be enabled via CLI or via configuration:
+
+```shell
+astro dev --experimentalJson
+astro build --experimentalJson
+astro sync --experimentalJson
+```
+
+```js
+// astro.config.mjs
+import { defineConfig, logHandlers } from "astro/config";
+
+export default defineConfig({
+  experimental: {
+    logger: logHandlers.json({
+      pretty: true,
+      level: 'warn'
+    }) 
+  }
+})
+```
+
+#### Custom logger
+
+You can also create your own custom logger by implementing the correct interface:
+
+```js
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+
+export default defineConfig({
+  experimental: {
+    logger: {
+      entrypoint: "@org/custom-logger"
+    }
+  }
+})
+```
+
+```ts
+// @org/custom-logger.js
+import type { AstroLoggerDestination, AstroLoggerMessage } from "astro"
+
+const customLogger: AstroLoggerDestination = {
+  write(message: AstroLoggerMessage) {
+    // write message somewhere
+  }
+} 
+export default customLogger
+```

packages/astro/src/actions/runtime/types.ts

@@ -105,6 +105,7 @@ export type ActionAPIContext = Pick<
 	| 'session'
 	| 'cache'
 	| 'csp'
+	| 'logger'
 >;
 
 export type MaybePromise<T> = T | Promise<T>;

packages/astro/src/container/index.ts

@@ -181,6 +181,7 @@ function createManifest(
 		experimentalQueuedRendering: manifest?.experimentalQueuedRendering ?? {
 			enabled: false,
 		},
+		experimentalLogger: manifest?.experimentalLogger ?? false,
 	};
 }
 
@@ -273,6 +274,7 @@ type AstroContainerManifest = Pick<
 	| 'assetsDir'
 	| 'image'
 	| 'experimentalQueuedRendering'
+	| 'experimentalLogger'
 >;
 
 type AstroContainerConstructor = {

packages/astro/src/core/app/types.ts

@@ -158,6 +158,8 @@ export type SSRManifest = {
 	};
 	internalFetchHeaders?: Record<string, string>;
 	logLevel: AstroLoggerLevel;
+	// This is temporary, and only used while the logger is experimental
+	experimentalLogger: boolean;
 };
 
 export type SSRActions = {

packages/astro/src/core/build/plugins/plugin-manifest.ts

@@ -388,5 +388,6 @@ async function buildManifest(
 		internalFetchHeaders,
 		logLevel: settings.logLevel,
 		shouldInjectCspMetaTags: shouldTrackCspHashes(settings.config.security.csp),
+		experimentalLogger: !!settings.config.experimental?.logger,
 	};
 }

packages/astro/src/core/logger/core.ts

@@ -1,18 +1,26 @@
 import colors from 'piccolore';
 
+/**
+ *
+ */
 export interface AstroLoggerDestination<T = unknown> {
 	/**
 	 * It receives a message and writes it into a destination
 	 */
 	write: (chunk: T) => void;
-	// NOTE: will document once we actually use it
+	/**
+	 * It dumps logs without closing the connection to the destination.
+	 * Method that can be used by specialized loggers.
+	 */
 	flush?: () => Promise<void> | void;
-	// NOTE: will document once we actually use it
+	/**
+	 * It dumps logs and closes the connection to the destination.
+	 * Method that can be used by specialized loggers.
+	 */
 	close?: () => Promise<void> | void;
 }
 
 // NOTE: this is a public type
-
 /**
  * The level of logging. Priority is the following:
  * 1. debug

packages/astro/src/core/logger/handlers.ts

@@ -1,24 +1,78 @@
 import type { LoggerHandlerConfig } from './config.js';
 import type { JonsHandlerConfig } from './impls/json.js';
+import type { NodeHandlerConfig } from './impls/node.js';
+import type { ConsoleHandlerConfig } from './impls/console.js';
 
 export const logHandlers = {
+	/**
+	 * It uses the built-in Astro JSON logger.
+	 * @example
+	 * ```js
+	 * export default defineConfig({
+	 *   experimental: {
+	 *     logger: logHandlers.json({ pretty: true })
+	 *   }
+	 * })
+	 * ```
+	 */
 	json(config?: JonsHandlerConfig): LoggerHandlerConfig {
 		return {
 			entrypoint: 'astro/logger/json',
 			config,
 		};
 	},
-	node(): LoggerHandlerConfig {
+	/**
+	 * It uses the built-in Astro Node.js logger.
+	 *
+	 * @example
+	 * ```js
+	 * export default defineConfig({
+	 *   experimental: {
+	 *     logger: logHandlers.node({ pretty: true })
+	 *   }
+	 * })
+	 * ```
+	 */
+	node(config?: NodeHandlerConfig): LoggerHandlerConfig {
 		return {
 			entrypoint: 'astro/logger/node',
+			config,
 		};
 	},
-	console(): LoggerHandlerConfig {
+	/**
+	 * It uses the built-in Astro console logger.
+	 *
+	 * @example
+	 * ```js
+	 * export default defineConfig({
+	 *   experimental: {
+	 *     logger: logHandlers.console({ pretty: true })
+	 *   }
+	 * })
+	 * ```
+	 */
+	console(config?: ConsoleHandlerConfig): LoggerHandlerConfig {
 		return {
 			entrypoint: 'astro/logger/console',
+			config,
 		};
 	},
 
+	/**
+	 * It allows composing different loggers
+	 *
+	 * @example
+	 * ```js
+	 * export default defineConfig({
+	 *   experimental: {
+	 *     logger: logHandlers.compose([
+	 *       logHandlers.console(),
+	 *       logHandlers.json(),
+	 *     ])
+	 *   }
+	 * })
+	 * ```
+	 */
 	compose(...loggers: LoggerHandlerConfig[]): LoggerHandlerConfig {
 		return {
 			entrypoint: 'astro/logger/compose',

packages/astro/src/core/logger/impls/console.ts

@@ -6,10 +6,16 @@ import {
 	type AstroLoggerLevel,
 	AstroLogger,
 } from '../core.js';
+import type { NodeHandlerConfig } from './node.js';
+
+export type ConsoleHandlerConfig = {
+	level?: AstroLoggerLevel;
+};
 
 function consoleLogDestination(
-	level: AstroLoggerLevel = 'info',
+	config: ConsoleHandlerConfig = {},
 ): AstroLoggerDestination<AstroLoggerMessage> {
+	const { level = 'info' } = config;
 	return {
 		write(event: AstroLoggerMessage) {
 			let dest = console.error;
@@ -37,9 +43,6 @@ export function createConsoleLogger({ level }: { level: AstroLoggerLevel }): Ast
 	});
 }
 
-type Options = {
-	level?: AstroLoggerLevel;
-};
-export default function (options?: Options): AstroLoggerDestination<AstroLoggerMessage> {
-	return consoleLogDestination(options?.level ?? 'info');
+export default function (options?: NodeHandlerConfig): AstroLoggerDestination<AstroLoggerMessage> {
+	return consoleLogDestination(options);
 }

packages/astro/src/core/logger/impls/json.ts

@@ -9,7 +9,13 @@ import type { Writable } from 'node:stream';
 import type { AstroInlineConfig } from '../../../types/public/index.js';
 
 export type JonsHandlerConfig = {
+	/**
+	 * Whether the JSON line should format on multiple lines
+	 */
 	pretty?: boolean;
+	/**
+	 * The level of logs that should be printed by the logger.
+	 */
 	level?: AstroLoggerLevel;
 };
 

packages/astro/src/core/logger/impls/node.ts

@@ -13,9 +13,14 @@ type ConsoleStream = Writable & {
 	fd: 1 | 2;
 };
 
+export type NodeHandlerConfig = {
+	level?: AstroLoggerLevel;
+};
+
 function nodeLogDestination(
-	level: AstroLoggerLevel = 'info',
+	config: NodeHandlerConfig = {},
 ): AstroLoggerDestination<AstroLoggerMessage> {
+	const { level = 'info' } = config;
 	return {
 		write(event: AstroLoggerMessage) {
 			let dest: ConsoleStream = process.stderr;
@@ -37,11 +42,8 @@ function nodeLogDestination(
 	};
 }
 
-type Options = {
-	level?: AstroLoggerLevel;
-};
-export default function (options?: Options): AstroLoggerDestination<AstroLoggerMessage> {
-	return nodeLogDestination(options?.level ?? 'info');
+export default function (options?: NodeHandlerConfig): AstroLoggerDestination<AstroLoggerMessage> {
+	return nodeLogDestination(options);
 }
 
 export function createNodeLoggerFromFlags(inlineConfig: AstroInlineConfig): AstroLogger {

packages/astro/src/core/logger/shared.ts

@@ -8,7 +8,7 @@ export const RESOLVED_LOGGER_MODULE_ID = '\0' + LOGGER_MODULE_ID;
 /**
  * Generates virtual module code for a logger factory given a `LoggerHandlerConfig`.
  * Handles built-in loggers (node, console, json), the compose meta-logger,
- * and arbitrary user-provided entrypoints.
+ * and arbitrary user-provided entrypoint.
  */
 export function generateLoggerCode(config: LoggerHandlerConfig): string {
 	switch (config.entrypoint) {

packages/astro/src/core/middleware/index.ts

@@ -121,6 +121,7 @@ function createContext({
 		session: undefined,
 		cache: new DisabledAstroCache(),
 		csp: undefined,
+		logger: undefined,
 	};
 	return Object.assign(context, {
 		getActionResult: createGetActionResult(context.locals),

packages/astro/src/core/render-context.ts

@@ -599,6 +599,27 @@ export class RenderContext {
 					},
 				};
 			},
+
+			get logger(): APIContext['logger'] {
+				if (!pipeline.manifest.experimentalLogger) {
+					pipeline.logger.warn(
+						null,
+						'The Astro.logger is available only when experimental.logger is defined.',
+					);
+					return undefined;
+				}
+				return {
+					info(msg: string) {
+						pipeline.logger.info(null, msg);
+					},
+					warn(msg: string) {
+						pipeline.logger.warn(null, msg);
+					},
+					error(msg: string) {
+						pipeline.logger.error(null, msg);
+					},
+				};
+			},
 		};
 	}
 
@@ -866,6 +887,19 @@ export class RenderContext {
 					},
 				};
 			},
+			get logger(): APIContext['logger'] {
+				return {
+					info(msg: string) {
+						pipeline.logger.info(null, msg);
+					},
+					warn(msg: string) {
+						pipeline.logger.warn(null, msg);
+					},
+					error(msg: string) {
+						pipeline.logger.error(null, msg);
+					},
+				};
+			},
 		};
 	}
 

packages/astro/src/manifest/serialized.ts

@@ -237,5 +237,6 @@ async function createSerializedManifest(
 		logLevel: settings.logLevel,
 		shouldInjectCspMetaTags: false,
 		experimentalQueuedRendering: settings.config.experimental?.queuedRendering,
+		experimentalLogger: !!settings.config.experimental?.logger,
 	};
 }

packages/astro/src/runtime/server/astro-global.ts

@@ -98,5 +98,8 @@ export function createAstro(site: string | undefined): AstroGlobal {
 		get cache(): any {
 			throw createError('cache');
 		},
+		get logger(): any {
+			throw createError('logger');
+		},
 	};
 }

packages/astro/src/types/public/config.ts

@@ -3064,9 +3064,26 @@ export interface AstroUserConfig<
 		 * @name experimental.logger
 		 * @type {{ entrypoint: string; config?: Record<string, unknown> }}
 		 * @default `undefined`
-		 * @version 6.0.0
+		 * @version 6.2.0
 		 * @description
-		 * Allows to customise how Astro logger behaves
+		 *
+		 * Configure a custom logger by providing the specifier to its entrypoint point and an optional, serializable configuration:
+		 *
+		 * ```js
+		 * // astro.config.mjs
+		 * import { defineConfig } from 'astro/config';
+		 *
+		 * export default defineConfig({
+		 *   experimental: {
+		 *     logger: {
+		 *       entrypoint: "@org/astro-logger",
+		 *       config: {
+		 *        level: "error"
+		 *       }
+		 *     }
+		 *   }
+		 * });
+		 * ```
 		 */
 		logger?: LoggerHandlerConfig;
 	};