hono-session

library1.2.0jsnpmunverified

Hono-session is a cookie-based session middleware for the Hono web framework. Offers both stateless (encrypted cookie) and external storage modes. The current stable version is 1.2.0, with frequent updates. Features session renewal, regeneration for preventing fixation attacks, flash messages, and reflash ability. Supports custom encryption via iron-webcrypto and stores like Map, file, or database. Built in TypeScript with global type augmentation. Requires Node.js >=18.18.0. Alternatives like @hono/sessions exist but hono-session is lighter and simpler.

devops

npm install hono-session

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HONO-SESSION

hono-session

devopsjavascriptv1.2.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

default

✓ import session from 'hono-session'

✗ const session = require('hono-session')

ESM-only; CommonJS require not supported.

Session

✓ import type { Session } from 'hono-session'

✗ import { Session } from 'hono-session'

Session is a type, must be imported with `import type` or used only in TypeScript.

createMiddleware

✓ import { createMiddleware } from 'hono-session'

Used for custom middleware to refine session types; available in v1.2.0+

Basic setup with login and user retrieval using stateless encrypted cookies.

import { Hono } from 'hono' import session from 'hono-session' const app = new Hono() app.use(session({ secret: process.env.SESSION_SECRET ?? 'my-secret-key-at-least-32-chars!!!', maxAge: 3600, // 1 hour })) app.post('/login', async (c) => { c.session.userId = 'user123' c.session.renew() await c.session.regenerate() // prevent fixation return c.text('Logged in') }) app.get('/me', async (c) => { const userId = c.session.userId if (!userId) return c.text('Unauthorized', 401) return c.text(`Hello ${userId}`) }) export default app

Debug

Known issues

breakingIn v1.0.0, the default export changed from a factory returning middleware to the middleware itself. Old usage `session()` no longer works; you must pass options directly to `session(options)`.

fix

Remove the extra function call: use `app.use(session({...}))` instead of `app.use(session()({...}))`

affects: <1.0.0

deprecatedThe `existsCookieName` option is deprecated in v1.2.0. It will be removed in a future major version.

fix

Avoid using `existsCookieName`. If you need a presence cookie, set it manually.

affects: >=1.2.0

gotchaSession secret must be at least 32 characters otherwise iron-webcrypto throws an error. No warning is given, only a cryptic error at runtime.

fix

Ensure secret is >=32 characters, or omit it for random secret (but sessions won't survive restart).

affects: >=1.0.0

gotchaWhen using external stores, the context object `c` is passed as the last argument to store methods but only if they are async functions. Omitting `c` argument will not cause an error but context won't be available.

fix

Always include `c` parameter in store methods (even if unused) to maintain consistency.

affects: >=1.0.0

gotchaTypeScript global augmentation must be imported: `import 'hono-session/global'` before declaring module. Forgetting this import leads to 'Cannot find name' errors.

fix

Add `import 'hono-session/global'` at top of the file or tsconfig include.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: iron-webcrypto.default.seal is not a function

Missing or incorrect import of iron-webcrypto; using a version incompatible with hono-session's import style.

fix

Ensure iron-webcrypto is installed and at version ^6.0.0. If using ESM, add `"type": "module"` to package.json.

Error: secret must be at least 32 characters

Secret provided is too short or missing (less than 32 characters).

fix

Provide a secret of at least 32 characters, or remove secret option to use auto-generated (sessions lost on restart).

Property 'session' does not exist on type 'Context'

Missing TypeScript type augmentation; the module declares session on c via global augmentation not loaded.

fix

Import 'hono-session/global' at top of file and ensure tsconfig includes the file. Alternatively use `c.get('session')`.

Cannot find module 'hono-session/global'

The library version (<1.0.0) does not have global augmentation file; or path is incorrect.

fix

Upgrade to v1.0.0 or later. If on older version, use `import 'hono-session/types'` instead.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

iron-webcryptooptionalDefault encryption/decryption for stateless sessions

Agent activity

5 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/kaelwd/hono-session ↗

packagehono-session ↗

homepagehttps://github.com/kaelwd/hono-session#readme ↗