From ffce4096bfc4a772a3765f76b785df7e75f3d781 Mon Sep 17 00:00:00 2001 From: Adam Chalemian Date: Wed, 15 Jul 2026 15:16:25 -0400 Subject: [PATCH 1/4] Document `session: false` opt-out and session runtime tree-shaking Accompanies withastro/astro#16871. --- .../guides/integrations-guide/cloudflare.mdx | 2 ++ .../en/guides/integrations-guide/netlify.mdx | 2 ++ .../en/guides/integrations-guide/node.mdx | 2 ++ src/content/docs/en/guides/sessions.mdx | 24 +++++++++++++++++++ .../docs/en/reference/api-reference.mdx | 4 ++-- .../docs/en/reference/modules/astro-fetch.mdx | 2 ++ 6 files changed, 34 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index c9f5b39c2c6f7..7ff2350b9fe18 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -354,6 +354,8 @@ const cart = await Astro.session?.get('cart'); By default, the KV binding is named `SESSION`. To use a different name, set the [`sessionKVBindingName`](#sessionkvbindingname) option in the adapter config. +If your project does not use sessions, you can set [`session: false`](/en/guides/sessions/#disabling-sessions) in your Astro config. The adapter will not configure a KV binding, no KV namespace will be provisioned when you deploy, and the session runtime will be excluded from your Worker bundle. + :::note Writes to Cloudflare KV are [eventually consistent](https://developers.cloudflare.com/kv/concepts/how-kv-works/#consistency) between regions. This means that changes are available immediately within the same region but may take up to 60 seconds to propagate globally. This won't affect most users as they are unlikely to switch regions between requests, but it may be a consideration for some use cases, such as VPN users. ::: diff --git a/src/content/docs/en/guides/integrations-guide/netlify.mdx b/src/content/docs/en/guides/integrations-guide/netlify.mdx index 9af376c29f86f..f7074c8bec7d8 100644 --- a/src/content/docs/en/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/en/guides/integrations-guide/netlify.mdx @@ -216,6 +216,8 @@ The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user d Astro automatically configures [Netlify Blobs](https://docs.netlify.com/blobs/overview/) for session storage when using the Netlify adapter. If you would prefer to use a different session storage driver, you can specify it in your Astro config. See [the `session` configuration reference](/en/reference/configuration-reference/#sessiondriver) for more details. +If your project does not use sessions, you can set [`session: false`](/en/guides/sessions/#disabling-sessions) in your Astro config. The adapter will not configure Netlify Blobs for session storage, and the session runtime will be excluded from your function bundle. + ### Caching Pages On-demand rendered pages without any dynamic content can be cached to improve performance and lower resource usage. diff --git a/src/content/docs/en/guides/integrations-guide/node.mdx b/src/content/docs/en/guides/integrations-guide/node.mdx index aab128b0774d8..7acd298fe0b16 100644 --- a/src/content/docs/en/guides/integrations-guide/node.mdx +++ b/src/content/docs/en/guides/integrations-guide/node.mdx @@ -295,6 +295,8 @@ The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user d Astro uses the local filesystem for session storage when using the Node adapter. If you would prefer to use a different session storage driver, you can specify it in your Astro config. See [the `session` configuration reference](/en/reference/configuration-reference/#sessiondriver) for more details. +If your project does not use sessions, you can set [`session: false`](/en/guides/sessions/#disabling-sessions) in your Astro config. The adapter will not configure the filesystem session driver, and the session runtime will be excluded from your server bundle. + ## Environment variables When using the [`astro:env`](/en/guides/environment-variables/#type-safe-environment-variables) secrets or `process.env` at runtime, neither Astro nor the adapter loads environment variables for you. diff --git a/src/content/docs/en/guides/sessions.mdx b/src/content/docs/en/guides/sessions.mdx index b10a0a7581941..f6e1d056ed79f 100644 --- a/src/content/docs/en/guides/sessions.mdx +++ b/src/content/docs/en/guides/sessions.mdx @@ -110,6 +110,30 @@ The following example takes advantage of [Unstorage compatibility](/en/reference ``` +## Disabling sessions + +

+ +

+ +If your project does not use sessions, you can set `session: false` to opt out of session support entirely: + +```js title="astro.config.mjs" ins={4} +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + session: false, +}); +``` + +When sessions are disabled, adapters that normally provide a default session driver (e.g. [Node](/en/guides/integrations-guide/node/#sessions), [Cloudflare](/en/guides/integrations-guide/cloudflare/#sessions), and [Netlify](/en/guides/integrations-guide/netlify/#sessions)) will not configure one, and the session runtime and its dependencies are excluded from your server bundle. This can be useful for serverless and edge runtimes, where a smaller bundle reduces cold start time. + +`Astro.session` and `context.session` will be `undefined`, exactly as in a project with no session storage configured. Code that checks for session availability (e.g. `Astro.session?.get()`) continues to work without changes. + +:::note +The session runtime is automatically excluded from your server bundle whenever no session driver is configured, even without setting `session: false`. Setting `session: false` additionally tells your adapter not to provide its default driver. +::: + ## Interacting with session data The [`session` object](/en/reference/api-reference/#session) allows you to interact with the stored user state (e.g. adding items to a shopping cart) and the session ID (e.g. deleting the session ID cookie when logging out). The object is accessible as `Astro.session` in your Astro components and pages and as `context.session` object in API endpoints, middleware, and actions. diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index f625b698cff42..263b86acc630a 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -893,7 +893,7 @@ Allows customizing how the cookie is serialized.

-**Type:** `AstroSession` +**Type:** `AstroSession | undefined` @@ -901,7 +901,7 @@ Allows customizing how the cookie is serialized. `session` is an object that allows data to be stored between requests for [routes rendered on demand](/en/guides/on-demand-rendering/). It is associated with a cookie that contains the session ID only: the data itself is not stored in the cookie. -The session is created when first used, and the session cookie is automatically set. The `session` object is `undefined` if no session storage has been configured, or if the current route is prerendered, and will log an error if you try to use it. +The session is created when first used, and the session cookie is automatically set. The `session` object is `undefined` if no session storage has been configured, if [sessions are disabled](/en/guides/sessions/#disabling-sessions) with `session: false`, or if the current route is prerendered, and will log an error if you try to use it. See [the session guide](/en/guides/sessions/) for more information on how to use sessions in your Astro project. diff --git a/src/content/docs/en/reference/modules/astro-fetch.mdx b/src/content/docs/en/reference/modules/astro-fetch.mdx index a0881a6e64251..22e7810584ea5 100644 --- a/src/content/docs/en/reference/modules/astro-fetch.mdx +++ b/src/content/docs/en/reference/modules/astro-fetch.mdx @@ -256,6 +256,8 @@ await sessions(state); // ...render pipeline... ``` +If no session driver is configured, or sessions are [disabled](/en/guides/sessions/#disabling-sessions) with `session: false`, this handler registers no provider and `ctx.session` will be `undefined`. + ### `trailingSlash()`

From 37c300fc2e4c0088b86148916a185dd1b3fb3738 Mon Sep 17 00:00:00 2001 From: Adam Chalemian Date: Fri, 24 Jul 2026 18:12:02 -0400 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Adam Chalemian Co-authored-by: Armand Philippot --- src/content/docs/en/guides/sessions.mdx | 4 +--- src/content/docs/en/reference/api-reference.mdx | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/guides/sessions.mdx b/src/content/docs/en/guides/sessions.mdx index f6e1d056ed79f..85cb14f5f7fbd 100644 --- a/src/content/docs/en/guides/sessions.mdx +++ b/src/content/docs/en/guides/sessions.mdx @@ -110,7 +110,7 @@ The following example takes advantage of [Unstorage compatibility](/en/reference ``` -## Disabling sessions +### Disabling sessions

@@ -128,8 +128,6 @@ export default defineConfig({ When sessions are disabled, adapters that normally provide a default session driver (e.g. [Node](/en/guides/integrations-guide/node/#sessions), [Cloudflare](/en/guides/integrations-guide/cloudflare/#sessions), and [Netlify](/en/guides/integrations-guide/netlify/#sessions)) will not configure one, and the session runtime and its dependencies are excluded from your server bundle. This can be useful for serverless and edge runtimes, where a smaller bundle reduces cold start time. -`Astro.session` and `context.session` will be `undefined`, exactly as in a project with no session storage configured. Code that checks for session availability (e.g. `Astro.session?.get()`) continues to work without changes. - :::note The session runtime is automatically excluded from your server bundle whenever no session driver is configured, even without setting `session: false`. Setting `session: false` additionally tells your adapter not to provide its default driver. ::: diff --git a/src/content/docs/en/reference/api-reference.mdx b/src/content/docs/en/reference/api-reference.mdx index 263b86acc630a..d164608b32f0d 100644 --- a/src/content/docs/en/reference/api-reference.mdx +++ b/src/content/docs/en/reference/api-reference.mdx @@ -901,7 +901,7 @@ Allows customizing how the cookie is serialized. `session` is an object that allows data to be stored between requests for [routes rendered on demand](/en/guides/on-demand-rendering/). It is associated with a cookie that contains the session ID only: the data itself is not stored in the cookie. -The session is created when first used, and the session cookie is automatically set. The `session` object is `undefined` if no session storage has been configured, if [sessions are disabled](/en/guides/sessions/#disabling-sessions) with `session: false`, or if the current route is prerendered, and will log an error if you try to use it. +The session is created when first used, and the session cookie is automatically set. The `session` object is `undefined` and will log an error when used in the following cases: no session storage has been configured, [sessions are disabled](/en/guides/sessions/#disabling-sessions), or the current route is prerendered. See [the session guide](/en/guides/sessions/) for more information on how to use sessions in your Astro project. From 9344ac4e475c935617ec4d53dd1a5d07e7ac816c Mon Sep 17 00:00:00 2001 From: Adam Chalemian Date: Fri, 24 Jul 2026 18:23:12 -0400 Subject: [PATCH 3/4] Move session opt-out callout to intro section sentence --- src/content/docs/en/guides/sessions.mdx | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/content/docs/en/guides/sessions.mdx b/src/content/docs/en/guides/sessions.mdx index 85cb14f5f7fbd..d8c665dac9e36 100644 --- a/src/content/docs/en/guides/sessions.mdx +++ b/src/content/docs/en/guides/sessions.mdx @@ -116,7 +116,7 @@ The following example takes advantage of [Unstorage compatibility](/en/reference

-If your project does not use sessions, you can set `session: false` to opt out of session support entirely: +The session runtime is automatically excluded from your server bundle whenever no session driver is configured. Setting `session: false` additionally tells your adapter not to provide its default driver, opting your project out of session support entirely: ```js title="astro.config.mjs" ins={4} import { defineConfig } from 'astro/config'; @@ -126,11 +126,7 @@ export default defineConfig({ }); ``` -When sessions are disabled, adapters that normally provide a default session driver (e.g. [Node](/en/guides/integrations-guide/node/#sessions), [Cloudflare](/en/guides/integrations-guide/cloudflare/#sessions), and [Netlify](/en/guides/integrations-guide/netlify/#sessions)) will not configure one, and the session runtime and its dependencies are excluded from your server bundle. This can be useful for serverless and edge runtimes, where a smaller bundle reduces cold start time. - -:::note -The session runtime is automatically excluded from your server bundle whenever no session driver is configured, even without setting `session: false`. Setting `session: false` additionally tells your adapter not to provide its default driver. -::: +Adapters that normally provide a default session driver (e.g. [Node](/en/guides/integrations-guide/node/#sessions), [Cloudflare](/en/guides/integrations-guide/cloudflare/#sessions), and [Netlify](/en/guides/integrations-guide/netlify/#sessions)) will not configure one. This can be useful for serverless and edge runtimes, where a smaller bundle reduces cold start time. ## Interacting with session data From eef9cd0d4830f0b67f486447fe4e0e0bb457d867 Mon Sep 17 00:00:00 2001 From: Adam Chalemian Date: Fri, 24 Jul 2026 18:23:13 -0400 Subject: [PATCH 4/4] Reword `sessions()` handler note --- src/content/docs/en/reference/modules/astro-fetch.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/modules/astro-fetch.mdx b/src/content/docs/en/reference/modules/astro-fetch.mdx index 22e7810584ea5..f907f6f1bfbe5 100644 --- a/src/content/docs/en/reference/modules/astro-fetch.mdx +++ b/src/content/docs/en/reference/modules/astro-fetch.mdx @@ -256,7 +256,7 @@ await sessions(state); // ...render pipeline... ``` -If no session driver is configured, or sessions are [disabled](/en/guides/sessions/#disabling-sessions) with `session: false`, this handler registers no provider and `ctx.session` will be `undefined`. +This handler registers no provider when no session driver is configured, or when [sessions are disabled](/en/guides/sessions/#disabling-sessions). In both cases, `ctx.session` will be `undefined`. ### `trailingSlash()`