{"id":18128,"library":"astro-cookie-session","title":"Astro Cookie Session","description":"Middleware for managing session data using cookies in Astro SSR applications. Current version 1.3.0 (released 2024-12, active development). Session data is encrypted and stored client-side in cookies, not on the server, making it suitable for stateless architectures. Supports TypeScript with type-safe session definitions and optional flash messages. Key differentiators: zero external dependencies beyond Astro, encryption of payloads (added in 1.3.0), simple API similar to remix-run session handling, and built-in flash message support.","status":"active","version":"1.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/koyopro/astro-cookie-session","tags":["javascript","astro","cookie","session","typescript"],"install":[{"cmd":"npm install astro-cookie-session","lang":"bash","label":"npm"},{"cmd":"yarn add astro-cookie-session","lang":"bash","label":"yarn"},{"cmd":"pnpm add astro-cookie-session","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Astro middleware and cookies API","package":"astro","optional":false}],"imports":[{"note":"Named export only; default import will not work.","wrong":"import createCookieSessionStorage from 'astro-cookie-session'","symbol":"createCookieSessionStorage","correct":"import { createCookieSessionStorage } from 'astro-cookie-session'"},{"note":"getSession is returned from createCookieSessionStorage, not directly exported from package.","wrong":"const session = getSession(Astro.cookies) // correct usage","symbol":"getSession","correct":"const { getSession } = createCookieSessionStorage<MyData>()"},{"note":"Define your own SessionData type and pass it as a generic to createCookieSessionStorage. No explicit type export from package.","wrong":"","symbol":"SessionData type (implicit)","correct":"type SessionData = { userId: string }"}],"quickstart":{"code":"// .env\nSECRET_KEY_BASE=$(openssl rand -hex 64)\n\n// astro.config.mjs\nimport { defineConfig } from 'astro/config';\nexport default defineConfig({ output: 'server' });\n\n// src/sessions.ts\nimport { createCookieSessionStorage } from 'astro-cookie-session';\ntype SessionData = { userId: string };\nexport const { getSession } = createCookieSessionStorage<SessionData>();\n\n// src/pages/index.astro\n---\nimport { getSession } from '../sessions';\nimport type { APIRoute } from 'astro';\n\nif (Astro.request.method === 'POST') {\n  const form = await Astro.request.formData();\n  const session = getSession(Astro.cookies);\n  session.set('userId', form.get('id') as string);\n}\nconst session = getSession(Astro.cookies);\nconst userId = session.get('userId');\n---\n{userId ? <p>Hello, {userId}!</p> : <form method=\"post\"><input type=\"text\" name=\"id\"/><button>Log in</button></form>}","lang":"typescript","description":"Setup SSR, create typed session storage, and use session in an Astro page to read/write encrypted cookies."},"warnings":[{"fix":"Regenerate all session data after upgrading to 1.3.0; old cookies are incompatible.","message":"In v1.3.0, payloads are now encrypted by default. Existing sessions without encryption will fail to decrypt.","severity":"breaking","affected_versions":"<1.3.0"},{"fix":"Generate key with: openssl rand -hex 64 and ensure no newline or extra characters.","message":"SECRET_KEY_BASE must be exactly 128 hex characters (openssl rand -hex 64 generates correct length). Using a key of different length will cause errors at runtime.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set output: 'server' in astro.config.mjs.","message":"Astro must be configured with output: 'server' (SSR mode). The middleware will not work in static export mode.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you pass the correct cookies object: Astro.cookies in pages, or the cookies param in API routes.","message":"The getSession function must be called with Astro.cookies (Astro 4+) or cookies (API routes). Using an incorrect argument will throw a runtime error.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Add SECRET_KEY_BASE to .env file and ensure Astro loads it (e.g., import 'dotenv/config' or use Astro's built-in env support).","cause":"Missing SECRET_KEY_BASE env variable or not loaded in Astro.","error":"Error: Encryption key not set. Please set SECRET_KEY_BASE environment variable."},{"fix":"Use named import: import { createCookieSessionStorage } from 'astro-cookie-session'","cause":"Attempting to import createCookieSessionStorage as default import.","error":"TypeError: Cannot destructure property 'getSession' of ... as it is undefined."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}