" }
+```
+
+#### JSON logger options
+
+
+**Type:** `{ pretty: boolean; level: AstroLoggerLevel; }`
+**Default:** `{ pretty: false, level: 'info' }`
+
+
+
+The `json` logger accepts the following options:
+
+- `pretty`: when `true`, the JSON log is printed on multiple lines. Defaults to `false`.
+- `level`: the [level](#log-level) of logs that should be printed.
+
+```js title="astro.config.mjs" {5} ins="json"
+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' }`
+
+
+
+The `console` logger accepts the following options:
+
+- `level`: the [level](#log-level) of logs that should be printed.
+
+```js title="astro.config.mjs" {5} ins="console"
+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`](https://nodejs.org/api/process.html#processstdout) and [`process.stderr`](https://nodejs.org/api/process.html#processstderr). 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' }`
+
+
+
+The `node` logger accepts the following options:
+
+- `level`: the [level](#log-level) of logs that should be printed.
+
+```js title="astro.config.mjs" {5} ins="node"
+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 broadcast to all loggers.
+
+The following example composes the console logger and JSON logger using the default log level:
+
+```js title="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`:
+
+```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
+
+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`](#astrologgermessage).
+
+#### `AstroLoggerDestination.flush()`
+
+
+
+**Type:** `() => Promise | 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`
+
+
+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()`](#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
+
+The following APIs can be imported from the `astro/logger` specifier.
+
+### `matchesLevel`
+
+
+
+**Type:** `matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel) => boolean`
+
+
+Given two [log levels](#log-level), it returns whether the first level matches the second level.
+
+```js
+import { matchesLevel } from "astro/logger";
+
+matchesLevel("error", "info"); // true
+matchesLevel("info", "error"); // false
+
+```
diff --git a/src/content/docs/en/reference/experimental-flags/svg-optimization.mdx b/src/content/docs/en/reference/experimental-flags/svg-optimization.mdx
index 5a9c2c9229667..f7a26412067ac 100644
--- a/src/content/docs/en/reference/experimental-flags/svg-optimization.mdx
+++ b/src/content/docs/en/reference/experimental-flags/svg-optimization.mdx
@@ -9,30 +9,30 @@ import Since from '~/components/Since.astro'
-**Type:** `boolean | object`
+**Type:** `SvgOptimizer`
**Default:** `false`
-This experimental feature enables automatic optimization of your [SVG components](/en/guides/images/#svg-components) using [SVGO](https://svgo.dev/) during build time.
+This experimental feature enables automatic optimization of your [SVG components](/en/guides/images/#svg-components) at build time.
When enabled, your imported SVG files used as components will be optimized for smaller file sizes and better performance while maintaining visual quality. This can significantly reduce the size of your SVG assets by removing unnecessary metadata, comments, and redundant code.
-To enable this feature with default settings, set it to `true` in your Astro config:
+To enable this feature, import the `svgoOptimizer()` helper in your Astro config and assign it to the experimental `svgOptimizer` flag:
```js title="astro.config.mjs" ins={5}
-import { defineConfig } from "astro/config"
+import { defineConfig, svgoOptimizer } from "astro/config";
export default defineConfig({
experimental: {
- svgo: true
+ svgOptimizer: svgoOptimizer()
}
-})
+});
```
## Usage
-No change to using SVG components is required to take advantage of this feature. With experimental `svgo` enabled, all your SVG component import files will be automatically optimized:
+No change to using SVG components is required to take advantage of this feature. With experimental SVG optimization enabled, all your SVG component import files will be automatically optimized:
```astro title="src/pages/index.astro"
---
@@ -46,32 +46,36 @@ The SVG will be optimized during the build process, resulting in smaller file si
Note that this optimization applies to every SVG component import in your project. It is not possible to opt out on a per-component basis.
-## Configuration
+## SVGO
-You can pass an [SVGO configuration object](https://github.com/svg/svgo#configuration) to customize optimization behavior:
+Astro provides one built-in optimizer using [SVGO](https://svgo.dev/):
-```js title="astro.config.mjs"
-export default defineConfig({
- experimental: {
- svgo: {
- multipass: true,
- floatPrecision: 2,
- plugins: [
- 'preset-default',
- 'removeXMLNS',
- {
- name: "removeXlink",
- params: {
- includeLegacy: true
- }
- }
- ]
+```js
+import { svgoOptimizer } from "astro/config"
+```
+
+### Configuration
+
+You can pass an object containing [SVGO configuration options](https://github.com/svg/svgo#configuration) to customize optimization behavior:
+
+```js
+svgoOptimizer({
+ multipass: true,
+ floatPrecision: 2,
+ plugins: [
+ 'preset-default',
+ 'removeXMLNS',
+ {
+ name: "removeXlink",
+ params: {
+ includeLegacy: true
+ }
}
- }
-})
+ ]
+});
```
-### `plugins`
+#### `plugins`
**Type:** `Array`
**Default:** `[]`
@@ -82,55 +86,47 @@ This can include SVGO's [`preset-default`](https://svgo.dev/docs/preset-default/
To use a plugin’s default configuration, add its name to the array. If you need more control, use the `overrides` parameter to customize specific plugins within `preset-default`, or pass an object with a plugin's `name` to override its individual parameters.
-```js title="astro.config.mjs"
-export default defineConfig({
- experimental: {
- svgo: {
- plugins: [
- {
- name: 'preset-default',
- params: {
- overrides: {
- convertPathData: false,
- convertTransform: {
- degPrecision: 1,
- transformPrecision: 3
- },
- inlineStyles: false
- },
+```js
+svgoOptimizer({
+ plugins: [
+ {
+ name: 'preset-default',
+ params: {
+ overrides: {
+ convertPathData: false,
+ convertTransform: {
+ degPrecision: 1,
+ transformPrecision: 3
},
+ inlineStyles: false
},
- 'removeXMLNS',
- {
- name: "removeXlink",
- params: {
- includeLegacy: true
- }
- }
- ]
+ },
+ },
+ 'removeXMLNS',
+ {
+ name: "removeXlink",
+ params: {
+ includeLegacy: true
+ }
}
- }
-})
+ ]
+});
```
-### Other configuration options
+#### Other configuration options
There are a few [SVGO configuration options](https://github.com/svg/svgo/blob/66d503a48c6c95661726262a3068053c429b06a9/lib/types.ts#L335), especially `floatPrecision` and `multipass`, that can be passed directly to your config object:
-```js title="astro.config.mjs"
-export default defineConfig({
- experimental: {
- svgo: {
- multipass: true,
- floatPrecision: 2
- }
- }
-})
+```js
+svgoOptimizer({
+ multipass: true,
+ floatPrecision: 2,
+});
```
The `multipass` option sets whether to run the optimization engine multiple times until no further optimizations are found. The `floatPrecision` option sets the number of decimal places to preserve globally, but can be overridden for a specific plugin by specifying a custom value in its `params` property.
-## Common use cases
+### Common use cases
SVGO provides an extensive [default plugin list](https://svgo.dev/docs/preset-default/) with opinionated optimizations. While using this preset is more convenient than adding each plugin individually, you may need to customize it further. For example, it may remove items or clean up too aggressively for your situation, especially when using animations.
@@ -138,76 +134,103 @@ SVGO provides an extensive [default plugin list](https://svgo.dev/docs/preset-de
You may want to preserve certain SVG attributes and elements, such as `