Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 2 additions & 0 deletions src/content/docs/en/guides/integrations-guide/cloudflare.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
:::
Expand Down
2 changes: 2 additions & 0 deletions src/content/docs/en/guides/integrations-guide/netlify.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions src/content/docs/en/guides/integrations-guide/node.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
18 changes: 18 additions & 0 deletions src/content/docs/en/guides/sessions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,24 @@ The following example takes advantage of [Unstorage compatibility](/en/reference
```
</Steps>

### Disabling sessions

<p>
<Since v="7.2.0" />
</p>

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.
Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/en/reference/api-reference.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -893,15 +893,15 @@ Allows customizing how the cookie is serialized.

<p>

**Type:** `AstroSession`
**Type:** `AstroSession | undefined`

<Since v="5.7.0" />

</p>

`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.

Expand Down
2 changes: 2 additions & 0 deletions src/content/docs/en/reference/modules/astro-fetch.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm torn about this. Can't we say "Registers the session provider when a driver is configured." (first sentence)?
I mean, "ctx.session is undefined when no session is configured" is the expected behavior. It makes sense to explain what this entails on the adapter pages, but I feel that here, it doesn't add any extra information.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don’t like how it reads either. But, I do like how we are reiterating the requirements/conditions for sessions being defined. That said, do we really need to be so verbose here? My only argument for keeping it would be that someone visiting the FetchState docs should be aware/reminded of this. Idk though. I don’t have a good suggestion or compromise.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, sorry, I should have specified that I’m mainly conflicted about the second sentence. Someone using sessions already has a way of knowing this and it might not be useful to repeat that (ie. we could repeat that everywhere we mention sessions...).

But, if you think this is helpful, I'm okay with that! I don't have a better idea and, as I said, this is non-blocking anyway.


### `trailingSlash()`

<p>
Expand Down
Loading