Experimental logger

Type: object
Default: undefined

أُضيفت في: astro@6.2.0 تجريبي

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.

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

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

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

Alternatively, you can enable JSON logging the dev, build and sync commands using the --experimentalJson flag:

astro dev --experimentalJson
astro sync --experimentalJson
astro build --experimentalJson

Built-in loggers

The feature comes with three built-in loggers.

logHandlers.json

A logger that outputs messages in a JSON format. A log would look like this:

{ "message": "<the message>", "label": "router", "level": "info", "time": "<UNIX timestamp>"  }

JSON logger options

Type: { pretty: boolean; level: AstroLoggerLevel; }
Default: { pretty: false, level: 'info' }

أُضيفت في: astro@6.2.0 تجريبي

The json logger accepts the following options:

• pretty: when true, the JSON log is printed on multiple lines. Defaults to false
• level: the level of logs that should be printed.

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

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

logHandlers.console

A logger that prints messages using the console as its destination. Based on the level of the message, it uses different channels:

• error messages are printed using console.error
• warn messages are printed using console.warn
• info messages are printed using console.info

Console logger options

Type: { level: AstroLoggerLevel }
Default: { level: 'info' }

أُضيفت في: astro@6.2.0 تجريبي

The console logger accepts the following options:

• level: the level of logs that should be printed.

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  experimental: {
    logger: logHandlers.console({ level: 'warn' })
  }
});

logHandlers.node

A logger that prints messages to process.stdout and process.stderr. Level error messages are printed to stderr, while the others are printed to stdout.

This is Astro’s default logger.

Node logger options

Type: { level: AstroLoggerLevel }
Default: { level: 'info' }

أُضيفت في: astro@6.2.0 تجريبي

The node logger accepts the following options:

• level: the level of logs that should be printed.

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  experimental: {
    logger: logHandlers.node({ level: 'warn' })
  }
});

logHandlers.compose

A particular function that allows configuring multiple loggers in an arbitrary order. The same message is broadcasted to all loggers.

The following example composes the console logger and JSON logger using the default log level:

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  experimental: {
    logger: logHandlers.compose(
      logHandlers.console(),
      logHandlers.json()
    )
  }
});

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:

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 with the required write() function:

@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 utility to understand if the message should be printed
      if (matchesLevel(message.level, level)) {
        // log message somewhere and take level into consideration
      }
    }
  }
}

export default orgLogger;

Runtime

The context object now exposes a logger object containing the following functions:

• error(), which emits an message with error level.
• warn(), which emits an message with warn level.
• info(), which emits an message with info level.

---
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 equals level is equal 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:

astro.config.mjs

import { defineConfig, logHandlers } from 'astro/config';

export default defineConfig({
  experimental: {
    logger: logHandlers.json({ level: "warn" })
  }
});

The astro/logger package exposes a matchesLevel() helper to check the log level. This can be useful when building a custom logger.

import { matchesLevel } from "astro/logger"

matchesLevel("error", "info");

Types reference

The following types can be imported from the astro specifier.

AstroLoggerDestination

This is the interface that custom loggers must implement.

AstroLoggerDestination.write()

Type: (message: AstroLoggerMessage) => void

A mandatory method called for each log and accepting an AstroLoggerMessage.

AstroLoggerDestination.flush()

Type: () => Promise<void> | void

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.

AstroLoggerDestination.close()

Type: () => Promise<void> | void

An optional function called before a server is shut down. This function is usually called by adapters such as @astrojs/node.

AstroLoggerLevel

The level of the message. Available variants:

• 'debug'
• 'info'
• 'warn'
• 'error'
• 'silent'

AstroLoggerMessage

Type: { label: string | null; level: AstroLoggerLevel; message: string; newLine: boolean; }

The incoming object from the AstroLoggerDestination.write() 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

The following APIs can me imported from the astro/logger specifier.

matchesLevel

Type: matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel) => boolean

Given two log levels, it returns whether the first level matches the second level.

import { matchesLevel } from "astro/logger"

matchesLevel("error", "info"); // true
matchesLevel("info", "error"); // false