Skip to content

Clarify usage of fs storage in Sessions with Cloudflare adapter #11708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Clarify usage of fs storage in Sessions with Cloudflare adapter #11708

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 3 additions & 1 deletion src/content/docs/en/guides/integrations-guide/cloudflare.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -394,7 +394,9 @@ Creating a custom `public/_routes.json` will override the automatic generation.

The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user data between requests. This can be used for things like user data and preferences, shopping carts, and authentication credentials. Unlike cookie storage, there are no size limits on the data, and it can be restored on different devices.

Astro automatically configures [Workers KV](https://developers.cloudflare.com/kv/) for session storage when using the Cloudflare adapter. Before using sessions, you need to create a KV namespace to store the data and configure a KV binding in your Wrangler config file. By default, Astro expects the KV binding to be named `SESSION`, but you can choose a different name if you prefer by setting the [`sessionKVBindingName`](#sessionkvbindingname) option in the adapter config.
Astro automatically configures [Workers KV](https://developers.cloudflare.com/kv/) for session storage when using the Cloudflare adapter in production. To avoid mistakes that could compromise your data or cause unexpected bills, the filesystem storage will be used during local development by default.
Copy link
Contributor

Choose a reason for hiding this comment

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

It's not to avoid mistakes. It's because we don't have access to KV when running in dev, because astro dev doesn't use wrangler. The same applies to the Netlify adapter when running without the Netlify CLI

Copy link
Member Author

Choose a reason for hiding this comment

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

Right, I assumed KV would be somewhat available as part of the Cloudflare runtime injected by the adapter, and we just replaced that with the fs driver for safety.

Maybe this works?

Suggested change
Astro automatically configures [Workers KV](https://developers.cloudflare.com/kv/) for session storage when using the Cloudflare adapter in production. To avoid mistakes that could compromise your data or cause unexpected bills, the filesystem storage will be used during local development by default.
Astro automatically configures [Workers KV](https://developers.cloudflare.com/kv/) for session storage when using the Cloudflare adapter in production. During development, since Cloudflare KV cannot be accessed in the Astro dev server, the filesystem storage will be used instead.

Copy link
Member

@alexanderniebuhr alexanderniebuhr May 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

@ascorbic You are right we don't have access to remote KV. But we do have access to Cloudflare's platformProxy. We shouldn't use custom logic to use fs, we should just rely on the local Proxy. I'll check the code and make sure to fix this.

Copy link
Contributor

Choose a reason for hiding this comment

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

Thanks @alexanderniebuhr. That would be great.

Copy link
Member

Choose a reason for hiding this comment

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

@alexanderniebuhr @yanthomasdev Friendly ping to check in on where we are with this PR!

Copy link
Member Author

Choose a reason for hiding this comment

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

@sarah11918, this PR probably won't be needed if we change Sessions to use the local KV that is available in the Cloudflare adapter. Since Alex mentioned he'd work through this issue during TBD I'd rather have this one sitting and possibly closed as soon as this resolves than to merge and then a few days later we change it again.


Before deploying, you need to create a KV namespace to store the data and configure a KV binding in your Wrangler config file. By default, Astro expects the KV binding to be named `SESSION`, but you can choose a different name if you prefer by setting the [`sessionKVBindingName`](#sessionkvbindingname) option in the adapter config.

<Steps>

Expand Down