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..d8c665dac9e36 100644 --- a/src/content/docs/en/guides/sessions.mdx +++ b/src/content/docs/en/guides/sessions.mdx @@ -110,6 +110,24 @@ The following example takes advantage of [Unstorage compatibility](/en/reference ``` +### Disabling sessions + +

+ +

+ +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'; + +export default defineConfig({ + session: false, +}); +``` + +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 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..d164608b32f0d 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` 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. diff --git a/src/content/docs/en/reference/modules/astro-fetch.mdx b/src/content/docs/en/reference/modules/astro-fetch.mdx index a0881a6e64251..f907f6f1bfbe5 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... ``` +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()`