Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createCookieSessionStorage
✓ import { createCookieSessionStorage } from 'astro-cookie-session'
✗ import createCookieSessionStorage from 'astro-cookie-session'
Named export only; default import will not work.
getSession
✓ const { getSession } = createCookieSessionStorage<MyData>()
✗ const session = getSession(Astro.cookies) // correct usage
getSession is returned from createCookieSessionStorage, not directly exported from package.
SessionData type (implicit)
✓ type SessionData = { userId: string }
Define your own SessionData type and pass it as a generic to createCookieSessionStorage. No explicit type export from package.
Setup SSR, create typed session storage, and use session in an Astro page to read/write encrypted cookies.
// .env
SECRET_KEY_BASE=$(openssl rand -hex 64)
// astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({ output: 'server' });
// src/sessions.ts
import { createCookieSessionStorage } from 'astro-cookie-session';
type SessionData = { userId: string };
export const { getSession } = createCookieSessionStorage<SessionData>();
// src/pages/index.astro
---
import { getSession } from '../sessions';
import type { APIRoute } from 'astro';
if (Astro.request.method === 'POST') {
const form = await Astro.request.formData();
const session = getSession(Astro.cookies);
session.set('userId', form.get('id') as string);
}
const session = getSession(Astro.cookies);
const userId = session.get('userId');
---
{userId ? <p>Hello, {userId}!</p> : <form method="post"><input type="text" name="id"/><button>Log in</button></form>}
Errors
Common errors & fixes
Error: Encryption key not set. Please set SECRET_KEY_BASE environment variable.
Missing SECRET_KEY_BASE env variable or not loaded in Astro.
fixAdd SECRET_KEY_BASE to .env file and ensure Astro loads it (e.g., import 'dotenv/config' or use Astro's built-in env support).
TypeError: Cannot destructure property 'getSession' of ... as it is undefined.
Attempting to import createCookieSessionStorage as default import.
fixUse named import: import { createCookieSessionStorage } from 'astro-cookie-session' Audit
Dependencies
astrorequiredRequired peer dependency for Astro middleware and cookies API