hono-sessions is a middleware library designed for the Hono web framework, providing robust cookie-based session management. Currently at version 0.8.1, the library is actively maintained with a focus on stability and features like `autoExtendExpiration` and improved type safety. It differentiates itself by supporting a wide array of runtimes, including Node.js (v20+), Deno, Bun, Cloudflare Workers, and Cloudflare Pages, leveraging the Web Crypto API for secure, encrypted cookies via `iron-webcrypto`. Key features include support for 'flash messages' (data deleted after one read), built-in Memory and Cookie storage drivers, extensible architecture for custom drivers (like Bun SQLite), and strong TypeScript typing for session variables. It offers a flexible approach to user session management, particularly powerful in serverless and edge environments where persistent server-side state might be impractical.
npm install hono-sessionsVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates basic session usage with `hono-sessions`, including setting and retrieving data, handling flash messages, and explicitly touching the session to extend its expiration. It configures `CookieStore` with essential options like `encryptionKey` and `cookieOptions`, and incorporates TypeScript types for session data.
Update your 'hono' package to version '^4.0.0' or newer: `npm install hono@^4.0.0` or `deno add hono@^4.0.0`.
Provide a strong, sufficiently long (>=32 chars) `encryptionKey` in the `sessionMiddleware` options. Consider using an environment variable for this: `encryptionKey: process.env.SESSION_SECRET ?? 'your-very-long-secret-key-here'`.
Verify that your runtime environment satisfies the Web Crypto API requirement. For Node.js, this means using version 20 or newer. Check your environment's documentation for Web Crypto API support.
Always include `path: '/'` within the `cookieOptions` object passed to `sessionMiddleware`.
Be aware that `session_key_rotation` will be ignored when `CookieStore` is active. This is expected behavior; no specific fix is required unless you're migrating to a stateful store where key rotation would become relevant.
Ensure you are using ESM `import { sessionMiddleware } from 'hono-sessions'` and that your environment supports ESM.Add a `encryptionKey` string (at least 32 characters long) to the `sessionMiddleware` configuration.
Upgrade your Node.js version to 20 or higher, or ensure you are running in an environment with Web Crypto API support (e.g., Deno, Bun, Cloudflare Workers).
Verify that `app.use('*', sessionMiddleware(...))` is correctly placed before any routes accessing `c.get('session')`. Also, ensure your 'hono' peer dependency is `^4.0.0` or newer.