Registry / devops / koa-generic-session

koa-generic-session

library2.3.1jsnpmunverified

Generic session middleware for Koa framework (current stable v2.3.1). Provides flexible session management with pluggable external stores (redis, mongo, etc.) and supports synchronous and generator-based session handling. Key differentiator: it only writes cookies when session data changes, supports rolling sessions, and exposes session ID via this.sessionId. Requires Node >=6 and Koa v2, with async/await support. Maintained by the Koa core team.

devops

npm install koa-generic-session

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KOA-GENERIC-SESSIO

koa-generic-session

devopsjavascriptv2.3.1

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 'koa-generic-session'

✗ const { session } = require('koa-generic-session')

Default import in ESM; in CJS use `const session = require('koa-generic-session')`

SessionStore interface

✓ import type { SessionStore } from 'koa-generic-session'

Type-only import for TypeScript; not available in runtime

MemoryStore

✓ import { MemoryStore } from 'koa-generic-session'

✗ const MemoryStore = require('koa-generic-session').MemoryStore

Named export for built-in memory store; also accessible via require in CJS

Shows basic session setup with Koa v2, external Redis store, incrementing a counter, and destroying a session.

import Koa from 'koa'; import session from 'koa-generic-session'; import redisStore from 'koa-redis'; const app = new Koa(); app.keys = ['secret-key']; app.use(session({ store: redisStore(), key: 'myapp.sid', prefix: 'myapp:sess:' })); app.use(async ctx => { if (ctx.path === '/count') { ctx.session.count = (ctx.session.count || 0) + 1; ctx.body = `Visits: ${ctx.session.count}`; } else if (ctx.path === '/clear') { ctx.session = null; ctx.body = 'Session cleared'; } else { ctx.body = 'Hello'; } }); app.listen(3000);

Debug

Known issues

breakingv2 requires Node >=6 and Koa v2 (async/await). v1 uses generators and Koa v1. Do not mix versions.

fix

Upgrade to Koa v2 and use async middleware. For Koa v1, stay on koa-generic-session@1.x.

affects: >=2.0.0

breakingSession cookie is only set when session data is modified. If you need a session cookie on every request, you must ensure session is touched.

fix

Set `rolling: true` in options to reset cookie and TTL on every response that touches the session.

affects: >=1.0.0

gotchaSetting ctx.session to null destroys the session but does not clear the cookie. The cookie will remain until the browser deletes it.

fix

To also clear cookie, explicitly set ctx.cookies.set(key, null) or use ctx.session = null and then manually delete cookie.

affects: >=1.0.0

gotchaThe ttl option is for store expiration, not cookie maxAge. Confusing these can lead to sessions being deleted prematurely.

fix

Set cookie.maxAge for browser cookie expiration, and ttl for store data expiration. They can be different.

affects: >=1.0.0

deprecatedBuilt-in MemoryStore is deprecated; use an external store like koa-redis or koa-generic-session-mongo for production.

fix

Replace MemoryStore with a persistent store or memory store from another package.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: session is not a function

Using require incorrectly or mixing default/named exports

fix

Use `const session = require('koa-generic-session')` (not destructured) or `import session from 'koa-generic-session'`

Error: Cannot find module 'koa-redis'

External store package not installed

fix

Run `npm install koa-redis` (or your chosen store) and ensure it is included in package.json

TypeError: this.regenerateSession is not a function

Using v2 API (async/await) but calling in generator context, or forgetting to use `yield` in v1

fix

Use `await ctx.regenerateSession()` in async functions (v2) or `yield this.regenerateSession()` in generator functions (v1)

Error: setSession is not a function

Calling saveSession without proper store or before middleware is applied

fix

Ensure session middleware is used before routes that call ctx.saveSession()

Upgrade

Version history

2.3.1latest on npm

Audit

Dependencies

koarequiredPeer dependency: Koa v2 framework required

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/koajs/generic-session ↗

packagekoa-generic-session ↗

homepagehttps://github.com/koajs/generic-session#readme ↗