How to use sessions in dev?

[fluid pawn]

I'm using the Cloudflare adapter. How can I use sessions during local dev

[merry ridge]

Hi @fluid pawn. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

To use sessions during local development with the Cloudflare adapter in Astro, you need to set up Workers KV locally and ensure your dev environment emulates the Cloudflare runtime.

Steps to Use Sessions in Local Dev with Cloudflare Adapter

1. Create a KV Namespace
   Use the Wrangler CLI to create a KV namespace for session storage:

   npx wrangler kv namespace create "SESSION"
   

   This will output a namespace ID.

2. Configure the KV Namespace in Wrangler
   Add the namespace to your wrangler.toml or wrangler.json:

   kv_namespaces = [
     { binding = "SESSION", id = "<KV_NAMESPACE_ID>" }
   ]
   

   or

   {
     "kv_namespaces": [
       { "binding": "SESSION", "id": "<KV_NAMESPACE_ID>" }
     ]
   }
   

   By default, Astro expects the binding to be named SESSION, but you can change this with the sessionKVBindingName option in your adapter config if needed.

3. Configure the Cloudflare Adapter in Astro
   In your astro.config.mjs, ensure the Cloudflare adapter is set up:

   import { defineConfig } from 'astro/config';
   import cloudflare from '@astrojs/cloudflare';
   
   export default defineConfig({
     adapter: cloudflare(),
   });
   

   If you use a custom KV binding name:

   export default defineConfig({
     adapter: cloudflare({
       sessionKVBindingName: 'MY_SESSION_BINDING',
     }),
   });
   

   See more on sessionKVBindingName

4. Run the Dev Server
   The Cloudflare adapter provides a local emulation of the Cloudflare runtime, including KV, via the platformProxy option (enabled by default). Just run:

   astro dev
   

   This will proxy requests and emulate Cloudflare bindings, allowing you to use sessions as you would in production. The local KV data is persisted to .wrangler/state/v3/ by default, but you can customize this with the platformProxy.persist option if needed.

   Example:

   export default defineConfig({
     adapter: cloudflare({
       platformProxy: {
         enabled: true,
         persist: { path: './.cache/wrangler/v3' }
       }
     }),
   });
   

   See platformProxy options

5. Preview with Wrangler (Optional)
   For a closer production emulation, you can use Wrangler to preview your build:

   // package.json
   "preview": "wrangler dev ./dist"
   

   See Preview with Wrangler

---

Note:

• Writes to Cloudflare KV are eventually consistent, but this is usually not an issue in local development.
• You do not need to manually configure a session driver; the Cloudflare adapter does this for you by default.

For more details, see the Cloudflare Sessions guide and Sessions documentation.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@fluid pawn Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[mighty matrix]

@fluid pawn did this solve your problem? I'm in a similar situation where it looks like the session does not persist across requests.

I haven't setup Cloudflare KV locally. I assumed Astro's dev server would use a simple in memory map during development, but looks like that's not the case as far as I can tell.