• Accepted Date: 2026-03-31
• Reference Issues/Discussions: Feature request: configurable loggers / json logging #908
• Author: @rburgst
• Champion(s): @ematipico
• Implementation PR: N/A

Summary

Add support for configurable log handlers in Astro, allowing users to replace the default console output with custom logging implementations (e.g. structured JSON).

Background & Motivation

Users deploying Astro SSR to production need structured logging for integration with log aggregation services like Kibana, Logstash, CloudWatch, and Grafana/Loki. Agents running builds and dev locally work better with JSON. Today, Astro's logger is hardcoded – BaseApp uses consoleLogDestination which cannot be replaced, even by adapter authors. Error logs in rendering are split across multiple lines and formatted for human reading, making them unparseable by log aggregation tools.

This is a common requirement for any production SSR deployment and has been widely requested for a long time (this is currently the most upvoted feature request).

Goals

• Allow users to configure a custom log handler that receives all Astro log output
• Support structured logging (JSON) for production deployments out of the box
• Provide a --json CLI flag for zero-config JSON output (e.g. astro build --json, astro dev --json)
• Follow the established { entrypoint, config } factory pattern used by session drivers, font providers etc
• Work across all scopes: build, dev, and SSR runtime
• Ensure Vite logs flow through the custom handler (they already route through Astro's logger)
• Ship under experimental.logger initially

Non-Goals

• Request-scoped child loggers with correlation IDs
• Replacing the debug package integration – separate concern
• Separate handlers per scope (build vs server) – single handler with platform detection if needed