Registry / web-framework / hono-sessions

hono-sessions

JSON →
library0.8.1jsnpmunverified

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-sessions
INSTALL
IMPORT
SIG · HONO-SESSIONS
H
hono-sessions
web-frameworkjavascriptv0.8.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

sessionMiddleware
import { sessionMiddleware } from 'hono-sessions'
const { sessionMiddleware } = require('hono-sessions')
The primary middleware function. 'hono-sessions' is an ESM-first package. Deno users can import from 'jsr:@jcs224/hono-sessions' or 'npm:hono-sessions'.
CookieStore
import { CookieStore } from 'hono-sessions'
import CookieStore from 'hono-sessions/CookieStore'
A common built-in storage driver for cookie-based sessions. All storage drivers are named exports.
Session
import { Session } from 'hono-sessions'
This type is crucial for providing strong typing for the session object within your Hono context, improving developer experience and preventing runtime errors related to session data access.

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.

import { Hono } from 'hono' import { Session, sessionMiddleware, CookieStore } from 'hono-sessions' // Add types to your session data for improved safety and autocomplete type SessionDataTypes = { 'counter': number, 'flashMessage'?: string } // Set up your Hono instance with session types const app = new Hono<{ Variables: { session: Session<SessionDataTypes>, session_key_rotation: boolean // Type for internal middleware variable } }>() const store = new CookieStore() app.use('*', sessionMiddleware({ store, // IMPORTANT: encryptionKey must be at least 32 characters long for CookieStore encryptionKey: process.env.SESSION_ENCRYPTION_KEY ?? 'super-secret-key-that-is-at-least-thirty-two-characters-long', expireAfterSeconds: 900, // Session expires after 15 minutes of inactivity autoExtendExpiration: true, // Automatically extends session on activity (default: true) cookieOptions: { sameSite: 'Lax', // Recommended for basic CSRF protection path: '/', // Required for the library to function correctly httpOnly: true, // Recommended to prevent client-side script access secure: process.env.NODE_ENV === 'production' // Use 'Secure' in production }, })) app.get('/', async (c) => { const session = c.get('session') const currentCounter = session.get('counter') || 0; session.set('counter', currentCounter + 1); const flash = session.getFlash('flashMessage'); if (flash) { console.log(`Flash message: ${flash}`); } return c.html(` <h1>You have visited this page ${session.get('counter')} times</h1> ${flash ? `<p style="color: green;">${flash}</p>` : ''} <p><a href="/set-flash">Set a flash message</a></p> <p><a href="/read">Read counter (and touch session)</a></p> `) }) app.get('/set-flash', async (c) => { const session = c.get('session'); session.setFlash('flashMessage', 'This is a one-time message!'); return c.redirect('/'); }); app.get('/read', (c) => { const session = c.get('session') session.touch() // Explicitly update the session expiration time return c.json({ counter: session.get('counter'), flash: session.getFlash('flashMessage') // This will be undefined after first read }) }) // For Bun, Cloudflare Workers, etc. // export default { // port: 3000, // fetch: app.fetch // } // For Deno // Deno.serve(app.fetch) // For Node.js (via Hono adapter) // import { serve } from '@hono/node-server'; // serve({ fetch: app.fetch, port: 3000 });
Debug
Known issues
breakingHono v4.0.0 or higher is required as a peer dependency. Ensure your 'hono' package meets this requirement to prevent type mismatches and runtime errors.
fix
Update your 'hono' package to version '^4.0.0' or newer: `npm install hono@^4.0.0` or `deno add hono@^4.0.0`.
affects: >=0.8.1
gotchaThe `encryptionKey` option is mandatory when using `CookieStore` and highly recommended for other storage drivers to ensure session data integrity and confidentiality. It must be at least 32 characters long.
fix
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'`.
affects: >=0.1.0
gotchaThe Web Crypto API is a required runtime dependency for `hono-sessions` due to its use of `iron-webcrypto` for encryption. Ensure your chosen runtime environment (e.g., Node.js v20+, Deno, Bun, Cloudflare Workers) supports this API.
fix
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.
affects: >=0.1.0
gotchaThe `cookieOptions.path` property must be set to `'/'` for `hono-sessions` to function correctly across all routes. If omitted or set incorrectly, sessions might not persist as expected.
fix
Always include `path: '/'` within the `cookieOptions` object passed to `sessionMiddleware`.
affects: >=0.1.0
gotchaThe `session_key_rotation` feature is explicitly stated to have no effect when using the `CookieStore` because cookie-only sessions lack server-side state that would benefit from key rotation.
fix
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.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: sessionMiddleware is not a function
Attempting to use CommonJS `require` syntax or incorrect named import for an ESM-only package.
fix
Ensure you are using ESM `import { sessionMiddleware } from 'hono-sessions'` and that your environment supports ESM.
Error: encryptionKey is required.
The `encryptionKey` was not provided in the `sessionMiddleware` options when using `CookieStore`.
fix
Add a `encryptionKey` string (at least 32 characters long) to the `sessionMiddleware` configuration.
ReferenceError: crypto is not defined (or similar Web Crypto API error)
The runtime environment does not support the Web Crypto API, or the Node.js version is too old (<v20).
fix
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).
TypeError: c.get is not a function
This typically indicates that the Hono `c` context does not have the `session` variable, likely due to the `sessionMiddleware` not being applied or a mismatch in Hono versions preventing context augmentation.
fix
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.
Upgrade
Version history
0.8.1latest on npm
Audit
Dependencies
honorequiredPeer dependency required for integration with the Hono web framework.
Agent activity
11 hits · last 30 days
node
10
OpenAI (training)
1
Resources