Configurable loggers / json logging by ematipico · Pull Request #1339 · withastro/roadmap

ematipico · 2026-04-08T13:44:46Z

Summary

// astro.config.mjs
import { defineConfig, logHandlers } from "astro/config";

export default defineConfig({
  experimental: {
    logger: logHandlers.json({ pretty: true }),
  },
});

astro dev --json

Links

florian-lefebvre · 2026-04-08T19:16:02Z

+
+# Unresolved Questions
+
+- `flush` and `close` are asynchronous functions, and in the presence of multiple handlers we might need to await them. Should we call them without await? I wouldn't want to delay rendering. How do we catch errors if they fail?


I imagine an adapter could provide something like waitUntil which doesn't block the request, otherwise block the request

Possibly, but probably we can forget of the flush function. We will revisit once waitUntil lands in the next minor

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>

matthewp · 2026-04-24T12:05:48Z

+});
+```
+
+### `logHandlers.node(config?)`


From the user perspective, is there any real difference between the console and node loggers? They do the same, right, one just only works in Node, in which case, why have it?

They don't do the same thing.

Node.js uses stdout/stderr to print the messages.

Console prints to console via info/warn/error

Console always prints to stdout/stderr though. Do you know if there's an advantage to having both? Or did you do it that way because we already had both in the codebase (which IIRC is just historical and not purposefully designed).

Console always prints to stdout/stderr though

Do you mean that the runtime (Node.js, workderd, etc.) does that? If so, then it's an implementation detail.

Or did you do it that way because we already had both in the codebase (which IIRC is just historical and not purposefully designed).

Yes we do. CLI and Pipeline use two different loggers. CLI uses a node.js logger, while the pipeline uses the console logger. Additionally, I didn't exclude the idea that a user could create a client logger, so I wanted to keep things open ended for now.

ematipico · 2026-05-15T10:35:24Z

Call for consensus is now open.

ascorbic · 2026-05-15T11:23:55Z

👍🏻 looks good

matthewp · 2026-05-15T12:12:43Z

👍 sounds good to me

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>

ematipico · 2026-05-18T12:30:05Z

@matthewp and @ascorbic please approve the PR :)

delucis · 2026-05-27T22:17:37Z

Just used a user query to dogfood this API — really handy way for people to customise stuff!

Here’s the custom logger I made in case it’s of interest: https://stackblitz.com/edit/github-cf392aa7?file=astro.config.mjs,custom-logger.js
And the Discord thread: https://discord.com/channels/830184174198718474/1509285901791006942

Some quick feedback/ideas based on trying it:

It would be nice to have a defineLogger() utility similar to our other type helpers. That would simplify some of the docs examples a bit potentially by not requiring as much manual typing.
It feels a shame that the options to a logger aren’t safely typed — definitely tricky because of the entrypoint pattern though.
The "SKIP_FORMAT" label might need to be documented or redesigned? Feels unexpected to have the label be used for something that isn’t actually a display label and likely for users to end up logging it instead of filtering it out like Astro’s implementations do.
I ended up copying Astro’s getEventPrefix() logic to be able to replicate Astro’s behaviour — I basically wanted a logger that was 1:1 to Astro’s default behaviour but had custom control over skipping some messages. Don’t know if that suggests there are more utilities that could be useful to users.

Take all that with a grain of salt as just the experience for a specific kind of logger. But thought it would be helpful to share.

florian-lefebvre · 2026-05-28T07:14:30Z

We decided against having defineLogger() because all similar APIs just use types FYI.

For the options type safety, that's good feedback. I think the RFC and the docs on custom loggers should be updated to match the official pattern:

function pinoLogger(config: Options): LoggerHandlerConfig {
	return {
		entrypoint: '...',
		config
	}
}

We have a similar situation for session drivers. You don't have to use this pattern but we only document this one because it's better DX

delucis · 2026-05-28T12:28:44Z

Oh, and just remembered another thing that tripped me up getting started:

The docs show adding a custom logger from an npm package entry point

      entrypoint: "@org/custom-logger",

But most often people will be adding a local file to their project when building a custom logger, I’d guess. Or at least would do so initially before bundling it up to be published. It took me quite a bit of trial and error to find a way to specify a local file that worked in all contexts, ending up with:

      entrypoint: fileURLToPath(new URL('./custom-logger.js', import.meta.url)),

That is definitely not super friendly — for most our APIs, e.g. like injectRoute(), we support passing a relative path like './custom-logger.js'. Would be good to support that here too.

ematipico marked this pull request as ready for review April 8, 2026 13:47

feat: astro logger

9309314

ematipico force-pushed the logger branch from 874c4f2 to 9309314 Compare April 8, 2026 13:49

ematipico changed the title ~~feat: astro logger~~ Configurable loggers / json logging Apr 8, 2026

ematipico mentioned this pull request Apr 8, 2026

Configurable loggers / json logging #1335

Closed

florian-lefebvre reviewed Apr 8, 2026

View reviewed changes

Comment thread proposals/0059-custom-logger.md

Comment thread proposals/0059-custom-logger.md Outdated

Comment thread proposals/0059-custom-logger.md Outdated

florian-lefebvre reviewed Apr 8, 2026

View reviewed changes

ematipico mentioned this pull request Apr 13, 2026

feat(logger): dev implementation withastro/astro#16304

Merged

update logger APIs

d4297d6

ematipico mentioned this pull request Apr 22, 2026

feat: astro logger withastro/docs#13787

Merged

Update proposals/0059-custom-logger.md

4a44db0

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>

matthewp reviewed Apr 24, 2026

View reviewed changes

Comment thread proposals/0059-custom-logger.md

matthewp reviewed Apr 24, 2026

View reviewed changes

Comment thread proposals/0059-custom-logger.md Outdated

matthewp reviewed Apr 28, 2026

View reviewed changes

Comment thread proposals/0059-custom-logger.md Outdated

ematipico added 4 commits April 28, 2026 15:22

Use correct astro logger destination

8acc87d

remove defineDestination

4851769

Document matchesLevel

d834e68

Don't use vite for loading the logger

9273d64

florian-lefebvre approved these changes May 18, 2026

View reviewed changes

Comment thread proposals/0059-custom-logger.md Outdated

Update proposals/0059-custom-logger.md

fdd9e13

Co-authored-by: Florian Lefebvre <contact@florian-lefebvre.dev>

matthewp approved these changes May 18, 2026

View reviewed changes

ematipico merged commit 590b89c into main Jun 8, 2026

ematipico deleted the logger branch June 8, 2026 13:14


		# Unresolved Questions

		- `flush` and `close` are asynchronous functions, and in the presence of multiple handlers we might need to await them. Should we call them without await? I wouldn't want to delay rendering. How do we catch errors if they fail?

Uh oh!

Conversation

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

Uh oh!

Summary

Links

Uh oh!

Uh oh!

Uh oh!

Uh oh!

florian-lefebvre Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

ematipico Apr 22, 2026

Choose a reason for hiding this comment

Uh oh!

matthewp Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

ematipico Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

matthewp Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

ematipico Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ematipico commented May 15, 2026

Uh oh!

ascorbic commented May 15, 2026

Uh oh!

matthewp commented May 15, 2026

Uh oh!

Uh oh!

ematipico commented May 18, 2026

Uh oh!

delucis commented May 27, 2026

Uh oh!

florian-lefebvre commented May 28, 2026

Uh oh!

delucis commented May 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

ematipico commented Apr 8, 2026 •

edited

Loading