feat: astro logger by ematipico · Pull Request #13787 · withastro/docs

ematipico · 2026-04-22T11:28:07Z

Description (required)

This PR adds documentation for the upcoming experimental logger. The RFC is here: withastro/roadmap#1339

Linear: AST-84

For Astro version: `6.2.0`. See astro PR #16437.

The attached PR is the one that mostly documents the new APIs

netlify · 2026-04-22T11:28:13Z

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	`0fd30f2`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/69e8b0cb1bff3d0008ed6906
😎 Deploy Preview	https://deploy-preview-13787--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

astrobot-houston · 2026-04-22T11:28:37Z

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/reference/experimental-flags/logger.mdx	Localization added, will be marked as complete.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

ArmandPhilippot

Thanks Ema! I left a few suggestions mostly around:

docs style, consistency with other experimental pages
and some reorganization to make it easier to scan. For example I find the API block placement a bit annoying currently:

API block between the introductory sentence and the list

Also, I noticed you mentioned the AstroLoggerDestination but I don't think we document its exact shape at the moment. It would be helpful to have a "Types reference" section with the public types/types required to build a custom logger.

Then, when the feature becomes stable we only need to reorganize the contents, everything would already be here.

For example, the experimental Route caching has an API reference but we could also use the same format used in the other references (e.g. Renderer types).

ArmandPhilippot · 2026-04-22T12:01:24Z

@@ -0,0 +1,218 @@
+---
+title: Configuring logger


We usually put "Experimental" in the title:

Suggested change

title: Configuring logger

title: Experimental logger

Or if you think this is important to keep "configuring" here:

Suggested change

title: Configuring logger

title: Experimental logger configuration

ArmandPhilippot · 2026-04-22T12:03:51Z

+
+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`.
+
+In the following example, we enable the built-in JSON logger, with a pretty output. 


We avoid "we" in docs:

Suggested change

In the following example, we enable the built-in JSON logger, with a pretty output.

The following example enables the built-in JSON logger, with a pretty output:

ArmandPhilippot · 2026-04-22T12:08:24Z

+<Since v="6.2.0" />
+</p>
+
+- `pretty`: when `true`, the JSON log in printed on multiple lines. Defaults to `false`


typo?

Suggested change

- `pretty`: when `true`, the JSON log in printed on multiple lines. Defaults to `false`

- `pretty`: when `true`, the JSON log is printed on multiple lines. Defaults to `false`

ArmandPhilippot · 2026-04-22T12:24:06Z

+The `json` function accepts the following options:
+
+<p>
+**Type:** `{ pretty: bool, level: AstroLoggerLevel }`<br />
+**Default:** `{ pretty: false, level: 'info' }`
+<Since v="6.2.0" />
+</p>


The API block before the list looks a bit weird in the preview. But I get the intent: this is the type for the configuration object not for logHandlers.json().

I wonder if a heading for the options could help here:

Suggested change

The `json` function accepts the following options:



**Type:** `{ pretty: bool, level: AstroLoggerLevel }` 

**Default:** `{ pretty: false, level: 'info' }`

<Since v="6.2.0" />



#### JSON logger options



**Type:** `{ pretty: boolean; level: AstroLoggerLevel; }` 

**Default:** `{ pretty: false, level: 'info' }`

<Since v="6.2.0" />



The `json` logger accepts the following options:

What do you think?

ArmandPhilippot · 2026-04-22T12:25:43Z

+The function accepts the following options:
+
+<p>
+**Type:** `{ level: AstroLoggerLevel }`<br />
+**Default:** `{ level: 'info' }`
+<Since v="6.2.0" />
+</p>


Same as before, this currently looks a bit weird in the preview and I wonder if a heading for the options could help here:

Suggested change

The function accepts the following options:



**Type:** `{ level: AstroLoggerLevel }` 

**Default:** `{ level: 'info' }`

<Since v="6.2.0" />



#### Console logger options



**Type:** `{ level: AstroLoggerLevel }` 

**Default:** `{ level: 'info' }`

<Since v="6.2.0" />



The `console` logger accepts the following options:

ArmandPhilippot · 2026-04-22T12:40:39Z

+
+Custom loggers must comply with the `AstroLoggerDestination` interface, and the function `write` is mandatory.


Then, this is no longer necessary:

Suggested change

Custom loggers must comply with the `AstroLoggerDestination` interface, and the function `write` is mandatory.

ArmandPhilippot · 2026-04-22T12:42:23Z

+
+## Runtime
+
+The types [context object](/en/reference/api-reference/#the-context-object) now expose `logger` object that exposes the following functions:


Maybe this is the barrier language but "types" sounds odd to me here. Could we use this instead:

Suggested change

The types [context object](/en/reference/api-reference/#the-context-object) now expose `logger` object that exposes the following functions:

The [context object](/en/reference/api-reference/#the-context-object) now exposes a `logger` object containing the following functions:

ArmandPhilippot · 2026-04-22T12:43:08Z

+
+## 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 equals level is equal or higher are printed.Custom


I guess this was the auto completion trying to add something after the dot?

Suggested change

A level is an internal, arbitrary score, assigned to each message. When a logger is configured with a certain level, only the messages with equals level is equal or higher are printed.Custom

A level is an internal, arbitrary score, assigned to each message. When a logger is configured with a certain level, only the messages with equals level is equal or higher are printed.

ArmandPhilippot · 2026-04-22T12:44:12Z

+1. `error`
+1. `warn`
+1. `info`


Well, this is correctly rendered but they all have the same score currently 😅

Suggested change

1. `error`

1. `warn`

1. `info`

1. `error`

2. `warn`

3. `info`

ArmandPhilippot · 2026-04-22T12:44:39Z

+1. `warn`
+1. `info`
+
+In the following example, we configure the JSON logger to print only messages that have the `warn` level or higher:


Same as earlier, we avoid "we" in docs:

Suggested change

In the following example, we configure the JSON logger to print only messages that have the `warn` level or higher:

The following example configures the JSON logger to print only messages that have the `warn` level or higher:

ematipico · 2026-04-22T13:54:29Z

Also, I noticed you mentioned the AstroLoggerDestination but I don't think we document its exact shape at the moment. It would be helpful to have a "Types reference" section with the public types/types required to build a custom logger.

I was hoping to get some suggestions on where to have it, and if it needs an header

ArmandPhilippot · 2026-04-22T14:28:13Z

If there is only one useful type, a reference section might not be the best approach and we could reshape Custom loggers with something similar to session drivers:

(we don't necessarily need to show write(), etc. in the sidebar, this was just to show the hierarchy)

Otherwise, a new section at the end might be easier to organize the content. Each section only describe what is available and we add links to the relevant types for advanced users. This remains easy to scan without having to scroll too much for those not interested in building their own logger. Something like:

And we have precedents for both approaches, so the structure remains familiar to users.

feat: astro logger

0fd30f2

ematipico mentioned this pull request Apr 22, 2026

feat(logger): docs and runtime withastro/astro#16437

Open

ArmandPhilippot reviewed Apr 22, 2026

View reviewed changes

ArmandPhilippot added this to the 6.2 milestone Apr 22, 2026

	title: Configuring logger
	title: Experimental logger configuration


		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`.

		In the following example, we enable the built-in JSON logger, with a pretty output.

	In the following example, we enable the built-in JSON logger, with a pretty output.
	The following example enables the built-in JSON logger, with a pretty output:

	- `pretty`: when `true`, the JSON log in printed on multiple lines. Defaults to `false`
	- `pretty`: when `true`, the JSON log is printed on multiple lines. Defaults to `false`


		Custom loggers must comply with the `AstroLoggerDestination` interface, and the function `write` is mandatory.


		## Runtime

		The types [context object](/en/reference/api-reference/#the-context-object) now expose `logger` object that exposes the following functions:

	The types [context object](/en/reference/api-reference/#the-context-object) now expose `logger` object that exposes the following functions:
	The [context object](/en/reference/api-reference/#the-context-object) now exposes a `logger` object containing the following functions:


		## 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 equals level is equal or higher are printed.Custom

	In the following example, we configure the JSON logger to print only messages that have the `warn` level or higher:
	The following example configures the JSON logger to print only messages that have the `warn` level or higher:

Uh oh!

Conversation

ematipico commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description (required)

For Astro version: 6.2.0. See astro PR #16437.

Uh oh!

netlify Bot commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

astrobot-houston commented Apr 22, 2026

Lunaria Status Overview

Tracked Files

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ematipico commented Apr 22, 2026

Uh oh!

ArmandPhilippot commented Apr 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ematipico commented Apr 22, 2026 •

edited

Loading

For Astro version: `6.2.0`. See astro PR #16437.

netlify Bot commented Apr 22, 2026 •

edited

Loading