Document session: false opt-out and session runtime tree-shaking

[adamchal]

Accompanies withastro/astro#16871.

Description (required)

Documents withastro/astro#16871, which adds a session: false config option to opt out of session support entirely, and tree-shakes the session runtime (AstroSession + unstorage) out of the SSR bundle for any project where no session driver is wired.

Changes (English only):

• guides/sessions.mdx: new "Disabling sessions" section (<Since v="7.2.0" />) covering the session: false option, that adapters skip wiring their default driver, that Astro.session/context.session are undefined (same as a project without sessions configured, so Astro.session?.get() feature detection keeps working), and a note that the runtime is tree-shaken automatically for any driver-less project even without the flag.
• reference/api-reference.mdx: session type corrected to AstroSession | undefined, and the disabled case added to the list of situations where session is undefined.
• guides/integrations-guide/cloudflare.mdx: note in the Sessions section that session: false means no KV binding is configured, no KV namespace is provisioned on deploy, and the session runtime is excluded from the Worker bundle.
• guides/integrations-guide/netlify.mdx: note that session: false means Netlify Blobs is not configured for session storage and the runtime is excluded from the function bundle.
• guides/integrations-guide/node.mdx: note that session: false means the filesystem driver is not configured and the runtime is excluded from the server bundle.
• reference/modules/astro-fetch.mdx: note on the sessions() pipeline handler that it registers no provider (and ctx.session is undefined) when no driver is configured or sessions are disabled.

References

• Related to feat(session): add session: false to opt out of session support astro#16871
• For Astro version 7.2.0 (and @astrojs/cloudflare 14.2.0, @astrojs/netlify 8.2.0, @astrojs/node 11.1.0)

Discord username: adam.chal

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/integrations-guide/cloudflare.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/netlify.mdx	Source changed, localizations will be marked as outdated.
en/guides/integrations-guide/node.mdx	Source changed, localizations will be marked as outdated.
en/guides/sessions.mdx	Source changed, localizations will be marked as outdated.
en/reference/api-reference.mdx	Source changed, localizations will be marked as outdated.
en/reference/modules/astro-fetch.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[github-actions]

Preview deployment

✅ Deployment complete!

• Latest commit: eef9cd0
• Preview: https://docs-session-false.previews.docs.astro.build
• Workflow run: View logs

[ArmandPhilippot]

I was waiting for Matt's block to be resolved before reviewing this PR in case anything change (so don't worry, it will be review in time!). So, this isn't a full review yet (I haven't checked the implementation), but here's a first pass!

Overall this looks good to me - thank you - but I think some parts could be improved to match our existing style (e.g. callout) and help everyone (including non native speaker) reading the English version (multiple if in a single sentence).

[ArmandPhilippot]

Except a nit, this LGTM and I won't block the PR for this! Thank you for handling the docs PR and the updates! 🙌🏽

[ArmandPhilippot]

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.

[adamchal]

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.

[ArmandPhilippot]

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.