feat: stable logger

astro.sidebar.ts

@@ -147,6 +147,7 @@ export const sidebar = [
 					'reference/dev-toolbar-app-reference',
 					'reference/session-driver-reference',
 					'reference/font-provider-reference',
+					'reference/logger-reference',
 					'reference/container-reference',
 					'reference/programmatic-reference',
 				],
@@ -162,7 +163,6 @@ export const sidebar = [
 					'reference/experimental-flags/queued-rendering',
 					'reference/experimental-flags/rust-compiler',
 					'reference/experimental-flags/advanced-routing',
-					'reference/experimental-flags/logger',
 				],
 			}),
 			'reference/legacy-flags',

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

@@ -1229,3 +1229,54 @@ content="
   "
 >
 ```
+### `logger`
+
+<p>
+
+  **Type**: `object | undefined`
+  <Since v="6.4.0" />
+</p>
+
+#### `error`
+<p>
+
+  **Type**: `(msg: string) => void`
+  <Since v="6.4.0" />
+</p>
+
+Emits a message with `error` level.
+
+```astro title="src/pages/index.astro"
+---
+Astro.logger.error("Can't find the checkout ID.");
+---
+```
+
+#### `warn`
+<p>
+
+  **Type**: `(msg: string) => void`
+  <Since v="6.4.0" />
+</p>
+Emits a message with `warn` level.
+
+```astro title="src/pages/index.astro"
+---
+Astro.logger.warn("Can't find the checkout ID.");
+---
+```  
+
+#### `info`
+<p>
+
+  **Type**: `(msg: string) => void`
+  <Since v="6.4.0" />
+</p>
+
+Emits a message with `info` level.
+
+```astro title="src/pages/index.astro"
+---
+Astro.logger.info("Can't find the checkout ID.");
+---
+```

src/content/docs/en/reference/experimental-flags/logger.mdx → src/content/docs/en/reference/logger-reference.mdx

@@ -1,47 +1,105 @@
 ---
-title: Experimental logger
+title: Astro Logger API
 sidebar:
-  label: Logger
-i18nReady: true
+  label: Logger API
+  i18nReady: true
 ---
-
 import Since from '~/components/Since.astro';
 
 <p>
-
-**Type:** `object`<br />
-**Default:** `undefined`<br />
-<Since v="6.2.0" />
+  <Since v="6.4.0" />
 </p>
 
-Enables an experimental, custom logger that can be controlled by the user. 
 
-When provided, the user has total control over the logs emitted by Astro. Additionally, the feature comes with some built-in loggers that can be used via the new `logHandlers`.
+Astro allows to customize, change and compose loggers.
+## Custom loggers
 
-The following example enables the built-in JSON logger, with a pretty output:
+You can create a custom logger by providing the correct configuration to the `logger` setting. It accepts an object with a mandatory `entrypoint`, the module where the logger is exported, and an optional configuration to pass to the logger. The configuration must be serializable.
 
-```js title="astro.config.mjs" {5} ins="logHandlers"
-import { defineConfig, logHandlers } from 'astro/config';
+The logger function must be exported as `default`.
+
+When you define a custom logger, you are in charge of all logs, even the ones emitted by Astro.
+
+The following example defines a custom logger exported by the `@org/custom-logger` package and accepting only one parameter to configure the logging `level`:
+
+```js title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
 
 export default defineConfig({
   experimental: {
-    logger: logHandlers.json({ pretty: true })
+    logger: {
+      entrypoint: "@org/custom-logger",
+      config: {
+        level: "warn"
+      }
+    }
   }
 });
 ```
 
-Alternatively, you can enable JSON logging for the `dev`, `build`, and `sync` commands using the `--experimentalJson` flag:
+The following example implements a minimal logger returning an [`AstroLoggerDestination` object](#astrologgerdestination) with the required `write()` function:
+
+```ts title="@org/custom-logger/index.ts"
+import type { 
+  AstroLoggerLevel, 
+  AstroLoggerDestination, 
+  AstroLoggerMessage 
+} from "astro";
+import { matchesLevel } from "astro/logger"; 
+
+type LoggerOptions = {
+  level: AstroLoggerLevel
+}
+
+function orgLogger(options: LoggerOptions = {}): AstroLoggerDestination {
+  const { level = 'info' } = options;
+  return {
+    write(message: AstroLoggerMessage) {
+      // Use this utility to understand if the message should be printed 
+      if (matchesLevel(message.level, level)) {
+        // log message somewhere and take the level into consideration
+      }
+    }
+  }
+}
+
+export default orgLogger;
+```
+
+
+
+## Log level
+
+A level is an internal, arbitrary score assigned to each message. When a logger is configured with a certain level, only the messages with a level equal to or higher are printed.
+
+There are three levels, from the highest to the lowest score:
+1. `error`
+2. `warn`
+3. `info`
+
+The following example configures the JSON logger to print only messages that have the `warn` level or higher:
+
+```js title="astro.config.mjs" {5} ins='level: "warn"'
+import { defineConfig, logHandlers } from 'astro/config';
 
-```shell
-astro dev --experimentalJson
-astro sync --experimentalJson
-astro build --experimentalJson
+export default defineConfig({
+  experimental: {
+    logger: logHandlers.json({ level: "warn" })
+  }
+});
 ```
 
+The `astro/logger` package exposes a [`matchesLevel()`](#matcheslevel) helper to check the log level. This can be useful when [building a custom logger](#custom-loggers).
+
+```js
+import { matchesLevel } from "astro/logger";
+
+matchesLevel("error", "info");
+```
 
 ## Built-in loggers
 
-The feature comes with three built-in loggers.
+Astro offers built-in loggers that applications can use.
 
 ### `logHandlers.json`
 
@@ -53,9 +111,9 @@ A logger that outputs messages in a JSON format. A log would look like this:
 #### JSON logger options
 
 <p>
-**Type:** `{ pretty: boolean; level: AstroLoggerLevel; }`<br />
-**Default:** `{ pretty: false, level: 'info' }`
-<Since v="6.2.0" />
+  **Type:** `{ pretty: boolean; level: AstroLoggerLevel; }`<br />
+  **Default:** `{ pretty: false, level: 'info' }`
+  <Since v="6.4.0" />
 </p>
 
 The `json` logger accepts the following options:
@@ -84,9 +142,9 @@ A logger that prints messages using the `console` as its destination. Based on t
 #### Console logger options
 
 <p>
-**Type:** `{ level: AstroLoggerLevel }`<br />
-**Default:** `{ level: 'info' }`
-<Since v="6.2.0" />
+  **Type:** `{ level: AstroLoggerLevel }`<br />
+  **Default:** `{ level: 'info' }`
+  <Since v="6.4.0" />
 </p>
 
 The `console` logger accepts the following options:
@@ -112,9 +170,9 @@ This is Astro's default logger.
 #### Node logger options
 
 <p>
-**Type:** `{ level: AstroLoggerLevel }`<br />
-**Default:** `{ level: 'info' }`
-<Since v="6.2.0" />
+  **Type:** `{ level: AstroLoggerLevel }`<br />
+  **Default:** `{ level: 'info' }`
+  <Since v="6.4.0" />
 </p>
 
 The `node` logger accepts the following options:
@@ -150,104 +208,7 @@ export default defineConfig({
 });
 ```
 
-## Custom loggers
-
-You can create a custom logger by providing the correct configuration to the `logger` setting. It accepts an object with a mandatory `entrypoint`, the module where the logger is exported, and an optional configuration to pass to the logger. The configuration must be serializable.  
-
-The logger function must be exported as `default`.
-
-When you define a custom logger, you are in charge of all logs, even the ones emitted by Astro. 
-
-The following example defines a custom logger exported by the `@org/custom-logger` package and accepting only one parameter to configure the logging `level`:
-
-```js title="astro.config.mjs"
-import { defineConfig } from 'astro/config';
-
-export default defineConfig({
-  experimental: {
-    logger: {
-      entrypoint: "@org/custom-logger",
-      config: {
-        level: "warn"
-      }
-    }
-  }
-});
-```
-
-The following example implements a minimal logger returning an [`AstroLoggerDestination` object](#astrologgerdestination) with the required `write()` function:
-
-```ts title="@org/custom-logger/index.ts"
-import type { 
-  AstroLoggerLevel, 
-  AstroLoggerDestination, 
-  AstroLoggerMessage 
-} from "astro";
-import { matchesLevel } from "astro/logger"; 
-
-type LoggerOptions = {
-  level: AstroLoggerLevel
-}
-
-function orgLogger(options: LoggerOptions = {}): AstroLoggerDestination {
-  const { level = 'info' } = options;
-  return {
-    write(message: AstroLoggerMessage) {
-      // Use this utility to understand if the message should be printed 
-      if (matchesLevel(message.level, level)) {
-        // log message somewhere and take the level into consideration
-      }
-    }
-  }
-}
-
-export default orgLogger;
-```
-
-## Runtime
-
-The [context object](/en/reference/api-reference/#the-context-object) now exposes a `logger` object containing the following functions:
-
-- `error()`, which emits a message with `error` level. 
-- `warn()`, which emits a message with `warn` level. 
-- `info()`, which emits a message with `info` level. 
-
-```astro
----
-Astro.logger.error("This is an error");
-Astro.logger.warn("This is a warning");
-Astro.logger.info("This is an info");
----
-```
-
-## Log level
-
-A level is an internal, arbitrary score assigned to each message. When a logger is configured with a certain level, only the messages with a level equal to or higher are printed.
-
-There are three levels, from the highest to the lowest score:
-1. `error`
-2. `warn`
-3. `info`
-
-The following example configures the JSON logger to print only messages that have the `warn` level or higher:
-
-```js title="astro.config.mjs" {5} ins='level: "warn"'
-import { defineConfig, logHandlers } from 'astro/config';
-
-export default defineConfig({
-  experimental: {
-    logger: logHandlers.json({ level: "warn" })
-  }
-});
-```
-
-The `astro/logger` package exposes a [`matchesLevel()`](#matcheslevel) helper to check the log level. This can be useful when [building a custom logger](#custom-loggers).
-
-```js
-import { matchesLevel } from "astro/logger";
 
-matchesLevel("error", "info");
-```
 
 
 ## Types reference
@@ -262,7 +223,7 @@ This is the interface that custom loggers must implement.
 
 <p>
 
-**Type:** `(message: AstroLoggerMessage) => void`
+  **Type:** `(message: AstroLoggerMessage) => void`
 </p>
 
 A mandatory method called for each log and accepting an [`AstroLoggerMessage`](#astrologgermessage).
@@ -271,7 +232,7 @@ A mandatory method called for each log and accepting an [`AstroLoggerMessage`](#
 
 <p>
 
-**Type:** `() => Promise<void> | void`
+  **Type:** `() => Promise<void> | void`
 </p>
 
 An optional function called at the end of each request. This is useful for advanced loggers that need to flush log messages while keeping the connection to the destination alive.
@@ -280,7 +241,7 @@ An optional function called at the end of each request. This is useful for advan
 
 <p>
 
-**Type:** `() => Promise<void> | void`
+  **Type:** `() => Promise<void> | void`
 </p>
 
 An optional function called before a server is shut down. This function is usually called by adapters such as `@astrojs/node`.
@@ -298,26 +259,26 @@ The level of the message. Available variants:
 
 <p>
 
-**Type:** `{ label: string | null; level: AstroLoggerLevel; message: string;	newLine: boolean; }`
+  **Type:** `{ label: string | null; level: AstroLoggerLevel; message: string;	newLine: boolean; }`
 </p>
 The incoming object from the [`AstroLoggerDestination.write()`](#astrologgerdestinationwrite) function:
 - `message`: the message being logged.
 - `level`: the level of the message.
 - `label`: an arbitrary label assigned to the log message.
 - `newLine`: whether this message should add a trailing newline.
 
-## APIs reference 
+## APIs reference
 
 The following APIs can be imported from the `astro/logger` specifier.
 
 ### `matchesLevel`
 
 <p>
 
-**Type:** `matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel) => boolean`
+  **Type:** `matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel) => boolean`
 </p>
 
-Given two [log levels](#log-level), it returns whether the first level matches the second level. 
+Given two [log levels](#log-level), it returns whether the first level matches the second level.
 
 ```js
 import { matchesLevel } from "astro/logger";