For greater flexibility and improved consistency with other Astro code, session drivers are now specified as an object:
import { defineConfig } from 'astro/config'
import { defineConfig, sessionDrivers } from 'astro/config'
export default defineConfig({
session: {
driver: 'redis',
options: {
url: process.env.REDIS_URL
},
driver: sessionDrivers.redis({
url: process.env.REDIS_URL
}),
}
})
Specifying the session driver as a string has been deprecated, but will continue to work until this feature is removed completely in a future major version. The object shape is the current recommended and documented way to configure a session driver.
#1444162ec8ea Thanks @upsuper! - Updates redirect handling to be consistent across static and server output, aligning with the behavior of other adapters.
Previously, the Node.js adapter used default HTML files with meta refresh tags when in static output. This often resulted in an extra flash of the page on redirect, while also not applying the proper status code for redirections. It’s also likely less friendly to search engines.
This update ensures that configured redirects are always handled as HTTP redirects regardless of output mode, and the default HTML files for the redirects are no longer generated in static output. It makes the Node.js adapter more consistent with the other official adapters.
No change to your project is required to take advantage of this new adapter functionality. It is not expected to cause any breaking changes. However, if you relied on the previous redirecting behavior, you may need to handle your redirects differently now. Otherwise you should notice smoother redirects, with more accurate HTTP status codes, and may potentially see some SEO gains.
#1451466a26d7 Thanks @matthewp! - Fixes compatibility issue with older versions of Astro by making getAllowedDomains() call optional and updating peer dependency to require astro@^5.14.3
#14188e3422aa Thanks @ascorbic! - Adds support for specifying a host to load prerendered error pages
By default, if a user defines a custom error page that is prerendered, Astro will load it from the same host as the one that the request is made to. This change allows users to specify a different host for loading prerendered error pages. This can be useful in scenarios such as where the server is running behind a reverse proxy or when prerendered pages are hosted on a different domain.
To use this feature, set the experimentalErrorPageHost adapter option in your Astro configuration to the desired host URL. For example, if your server is running on localhost and served via a proxy, you can ensure the prerendered error pages are fetched via the localhost URL:
import { defineConfig } from'astro/config';
import node from'@astrojs/node';
exportdefaultdefineConfig({
adapter: node({
// If your server is running on localhost and served via a proxy, set the host like this to ensure prerendered error pages are fetched via the localhost URL
#14012a125a14 Thanks @florian-lefebvre! - Adds a new experimental configuration option experimentalDisableStreaming to allow you to opt out of Astro’s default HTML streaming for pages rendered on demand.
HTML streaming helps with performance and generally provides a better visitor experience. In most cases, disabling streaming is not recommended.
However, when you need to disable HTML streaming (e.g. your host only supports non-streamed HTML caching at the CDN level), you can now opt out of the default behavior:
When the feature is enabled via the option experimentalStaticHeaders, and experimental Content Security Policy is enabled, the adapter will generate Response headers for static pages, which allows support for CSP directives that are not supported inside a <meta> tag (e.g. frame-ancestors).
#135272fd6a6b Thanks @ascorbic! - The experimental session API introduced in Astro 5.1 is now stable and ready for production use.
Sessions are used to store user state between requests for on-demand rendered pages. You can use them to store user data, such as authentication tokens, shopping cart contents, or any other data that needs to persist across requests:
---
exportconstprerender=false; // Not needed with 'server' output
constcart=await Astro.session.get('cart');
---
<ahref="/checkout">🛒 {cart?.length??0} items</a>
Configuring session storage
Sessions require a storage driver to store the data. The Node, Cloudflare and Netlify adapters automatically configure a default driver for you, but other adapters currently require you to specify a custom storage driver in your configuration.
If you are using an adapter that doesn’t have a default driver, or if you want to choose a different driver, you can configure it using the session configuration option:
import { defineConfig } from'astro/config';
import vercel from'@astrojs/vercel';
exportdefaultdefineConfig({
adapter: vercel(),
session: {
driver: 'upstash',
},
});
Using sessions
Sessions are available in on-demand rendered pages, API endpoints, actions and middleware.
In pages and components, you can access the session using Astro.session:
---
constcart=await Astro.session.get('cart');
---
<ahref="/checkout">🛒 {cart?.length??0} items</a>
In endpoints, actions, and middleware, you can access the session using context.session:
exportasyncfunctionGET(context) {
constcart=await context.session.get('cart');
return Response.json({ cart });
}
If you attempt to access the session when there is no storage driver configured, or in a prerendered page, the session object will be undefined and an error will be logged in the console:
---
exportconstprerender=true;
constcart=await Astro.session?.get('cart'); // Logs an error. Astro.session is undefined
---
Upgrading from Experimental to Stable
If you were previously using the experimental API, please remove the experimental.session flag from your configuration: