Skip to content

fix(v7): logger API no longer experimental #14027

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ArmandPhilippot merged 7 commits into from
Jun 9, 2026
Merged

fix(v7): logger API no longer experimental #14027

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0d9ebca
logger API fixes
ArmandPhilippot Jun 9, 2026
9dc7446
link to log handlers in the astro config module
ArmandPhilippot Jun 9, 2026
1fd8934
Update v7 upgrade guide: experimental flags, src/app.ts, @astrojs/db …
matthewp May 27, 2026
92224c0
add logger to the upgrade guide
ArmandPhilippot Jun 9, 2026
028ea78
Merge branch 'v7' into armand/v7-logger-nits
ArmandPhilippot Jun 9, 2026
4815d51
fix link
ArmandPhilippot Jun 9, 2026
28043de
Merge branch 'v7' into armand/v7-logger-nits
ArmandPhilippot Jun 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 11 additions & 10 deletions src/content/docs/en/guides/upgrade-to/v7.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,27 +78,28 @@ If you are using Vite-specific plugins, configuration, or APIs, check the [Vite

Most Astro users should be able to upgrade without any changes to their project code. This is primarily a breaking change for Astro integrations and plugins that depend on Vite internals.

### Rust Compiler
### Experimental Flags

The Rust-based Astro compiler, previously available as an experimental flag (`experimental.rustCompiler`), is now the default and only compiler in Astro 7. The Rust compiler delivers significantly faster build times compared to the previous Go-based compiler.
Experimental flags allow you to opt in to features while they are in early development. The following experimental flags have been removed in Astro 7.0 and are now stable, or the new default behavior.

##### What should I do?

No action is required for most projects. The Rust compiler is a drop-in replacement for the Go-based compiler.

If you had previously opted in to the Rust compiler via the experimental flag, you can now remove it from your configuration:
Remove these experimental flags from your Astro config if you were previously using them:

```js title="astro.config.mjs" del={4-6}
```js del={5-6} title="astro.config.mjs"
import { defineConfig } from 'astro/config';

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

If you encounter any issues with the Rust compiler, please report them on [GitHub](https://github.com/withastro/astro/issues).
#### Experimental features now stable:

- `logger`: The new logging system is now stable and the experimental flag is no longer needed to use it. If you were using this flag, you can now set your logger directly in the top-level `logger` field of your Astro config.

- `rustCompiler`: The Rust-based Astro compiler is now the default and only compiler, replacing the previous Go-based compiler. No action is required for most projects. If you encounter any issues, please report them on [GitHub](https://github.com/withastro/astro/issues).

## Removed

Expand Down
49 changes: 14 additions & 35 deletions src/content/docs/en/reference/logger-reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,10 @@ The following example defines a custom logger exported by the `@org/custom-logge
import { defineConfig } from 'astro/config';

export default defineConfig({
experimental: {
logger: {
entrypoint: "@org/custom-logger",
config: {
level: "warn"
}
logger: {
entrypoint: "@org/custom-logger",
config: {
level: "warn"
}
}
});
Expand Down Expand Up @@ -86,9 +84,7 @@ The following example configures the JSON logger to print only messages that hav
import { defineConfig, logHandlers } from 'astro/config';

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

Expand Down Expand Up @@ -128,9 +124,7 @@ The `json` logger accepts the following options:
import { defineConfig, logHandlers } from 'astro/config';

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

Expand Down Expand Up @@ -158,9 +152,7 @@ The `console` logger accepts the following options:
import { defineConfig, logHandlers } from 'astro/config';

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

Expand All @@ -186,13 +178,11 @@ The `node` logger accepts the following options:
import { defineConfig, logHandlers } from 'astro/config';

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

### `logHandlers.compose`
### `logHandlers.compose()`

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

Expand All @@ -202,18 +192,13 @@ The following example composes the console logger and JSON logger using the defa
import { defineConfig, logHandlers } from 'astro/config';

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




## Types reference

The following types can be imported from the `astro` specifier.
Expand Down Expand Up @@ -251,13 +236,6 @@ An optional function called before a server is shut down. This function is usual

### `AstroLoggerLevel`

The level of the message. Available variants:
- `'debug'`
- `'info'`
- `'warn'`
- `'error'`
### `AstroLoggerLevel`

<p>

**Type:** `'debug' |'info' |'warn' | 'error' | 'silent'`
Expand All @@ -274,6 +252,7 @@ Specifies the verbosity level of logs:

**Type:** `{ label: string | null; level: AstroLoggerLevel; message: string; newLine: boolean; }`
</p>

The incoming object from the [`AstroLoggerDestination.write()`](#astrologgerdestinationwrite) function:
- `message`: the message being logged.
- `level`: the level of the message.
Expand Down
11 changes: 11 additions & 0 deletions src/content/docs/en/reference/modules/astro-config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,6 +138,7 @@
envField,
fontProviders,
getViteConfig,
logHandlers,
mergeConfig,
passthroughImageService,
sessionDrivers,
Expand Down Expand Up @@ -307,6 +308,16 @@

Retrieves the Vite configuration to use by merging a custom Vite configuration object and an optional Astro configuration object. This is useful [to set up Vitest for testing](/en/guides/testing/#vitest).

### `logHandlers`

<p>

**Type:** `object`<br />
<Since v="7.0.0" />
</p>

Describes the [available built-in log handlers](/en/reference/logger-reference/#built-in-loggers) that can be used to [configure a logger](/en/reference/configuration-reference/#logger) in your Astro configuration.

Check failure on line 319 in src/content/docs/en/reference/modules/astro-config.mdx

View workflow job for this annotation

GitHub Actions / Check Links 

Broken fragment link in src/content/docs/en/reference/modules/astro-config.mdx, line 319: The linked page does not contain a fragment with the name "#logger". Available fragments: #theme-icons, #gradient, #starlight__sidebar, #__tab-tutorial, #__tab-guide, #__tab-reference, #__tab-ecosystem, #starlight__mobile-toc, #starlight__on-this-page--mobile, #starlight__on-this-page, #learn-astro-course-1, #_top, #top-level-options, #site, #base, #trailingslash, #redirects, #output, #adapter, #integrations, #root, #examples, #srcdir, #publicdir, #outdir, #cachedir, #compresshtml, #scopedstylestrategy, #prerenderconflictbehavior, #vite, #examples-1, #security, #securitycheckorigin, #securityalloweddomains, #securityactionbodysizelimit, #securityserverislandbodysizelimit, #securitycsp, #securitycspalgorithm, #securitycspdirectives, #securitycspstyledirective, #securitycspstyledirectivehashes, #securitycspstyledirectiveresources, #securitycspscriptdirective, #securitycspscriptdirectivehashes, #securitycspscriptdirectiveresources, #securitycspscriptdirectivestrictdynamic, #build-options, #buildformat, #effect-on-astrourl, #buildclient, #buildserver, #buildassets, #buildassetsprefix, #buildserverentry, #buildredirects, #buildinlinestylesheets, #buildconcurrency, #server-options, #serverhost, #serverport, #serverallowedhosts, #serveropen, #serverheaders, #session-options, #sessiondriver, #sessionoptions, #sessioncookie, #sessionttl, #dev-toolbar-options, #devtoolbarenabled, #devtoolbarplacement, #prefetch-options, #prefetchprefetchall, #prefetchdefaultstrategy, #image-options, #imageendpoint, #imageservice, #imageserviceconfiglimitinputpixels, #imageserviceconfigkernel, #imageserviceconfigjpeg, #imageserviceconfigwebp, #imageserviceconfigavif, #imageserviceconfigpng, #imagedangerouslyprocesssvg, #imagedomains, #imageremotepatterns, #imageresponsivestyles, #imagelayout, #imageobjectfit, #imageobjectposition, #imagebreakpoints, #markdown-options, #markdownshikiconfig, #markdownsyntaxhighlight, #markdownsyntaxhighlighttype, #markdownsyntaxhighlightexcludelangs, #markdownremarkplugins, #markdownrehypeplugins, #markdowngfm, #markdownsmartypants, #markdownremarkrehype, #markdownprocessor, #i18n, #i18nlocales, #i18ndefaultlocale, #i18nfallback, #example, #i18nrouting, #i18nroutingprefixdefaultlocale, #i18nroutingredirecttodefaultlocale, #i18nroutingfallbacktype, #i18ndomains, #env, #envschema, #envvalidatesecrets, #fonts, #fontprovider, #fontname, #fontcssvariable, #fontfallbacks, #fontoptimizedfallbacks, #fontweights, #fontstyles, #fontsubsets, #fontformats, #fontoptions, #fontdisplay, #fontunicoderange, #fontstretch, #fontfeaturesettings, #fontvariationsettings, #docsearch-lvl0, #learn-astro-course-2

### `mergeConfig()`

See [`mergeConfig()` in the Programmatic API reference](/en/reference/programmatic-reference/#mergeconfig).
Expand Down
Loading