Registry / web-framework / express-session

express-session

JSON →
library1.19.0jsnpmunverified

express-session is a robust and widely-used session middleware for Express.js applications, currently stable at version 1.19.0. It provides server-side session storage, managing session IDs via cookies while keeping the actual session data on the server, which is a key security differentiator compared to client-side cookie storage. While the core package offers a default `MemoryStore` for development and debugging, it explicitly warns against its use in production due to memory leak risks and lack of scalability, promoting a rich ecosystem of compatible external session stores. The project maintains a steady release cadence, with recent updates focusing on features like dynamic cookie options, improved security tooling, and dependency updates, ensuring ongoing compatibility and enhancements for Node.js environments (supporting Node.js >= 0.8.0). It has evolved to directly manage session cookies, making the `cookie-parser` middleware optional and recommending careful use if both are present to avoid secret mismatches.

npm install express-session
INSTALL
IMPORT
SIG · EXPRESS-SESSION
E
express-session
web-frameworkjavascriptv1.19.0
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.

session
import session from 'express-session'
import { session } from 'express-session'
The primary export is a default function that creates the middleware.
session
const session = require('express-session')
const { session } = require('express-session')
CommonJS require imports the default middleware factory function.
SessionStore
import { Store } from 'express-session'; // For type hinting custom stores
import { SessionStore } from 'express-session'; // Incorrect export name for type
To implement a custom session store, you would typically extend the `Store` class, which is a named export for TypeScript purposes. However, the `Store` class is not directly exported for runtime use as a typical named import, it's more for type definitions and extension.

This example demonstrates how to set up `express-session` with basic configuration for a view counter. It highlights essential cookie options like `secure`, `httpOnly`, and `maxAge`, and includes a critical warning about not using the default `MemoryStore` in production, emphasizing the use of environment variables for secrets.

const express = require('express'); const session = require('express-session'); const app = express(); const port = 3000; // WARNING: The default MemoryStore is NOT production-ready. // For production, use a compatible session store like connect-redis, connect-mongo, or memorystore. // For a list of stores, see compatible session stores section in the README. app.use(session({ secret: process.env.SESSION_SECRET ?? 'a very strong secret key that should be in an environment variable', // ALWAYS use a strong, environment-variable-backed secret resave: false, // Don't save session if unmodified saveUninitialized: true, // Save new but uninitialized sessions (e.g., before user logs in) cookie: { secure: process.env.NODE_ENV === 'production', // Use secure cookies in production (requires HTTPS) httpOnly: true, // Prevent client-side JavaScript access to cookie (mitigates XSS) maxAge: 24 * 60 * 60 * 1000 // Session expires after 24 hours (in milliseconds) } })); app.get('/', (req, res) => { if (req.session.views) { req.session.views++; res.send(`<h1>Welcome back!</h1><p>You have visited this page ${req.session.views} times.</p><p>Your session ID is: ${req.sessionID}</p>`); } else { req.session.views = 1; res.send(`<h1>Hello, New User!</h1><p>You have visited this page ${req.session.views} time.</p><p>Your session ID is: ${req.sessionID}</p>`); } }); app.listen(port, () => { console.log(`Server listening at http://localhost:${port}`); console.log('Try visiting a few times and then refresh after some time to see the session count.'); console.log('For production, ensure `secure: true` for cookies and that your app runs over HTTPS.'); });
Debug
Known issues
gotchaThe default `MemoryStore` provided by `express-session` is explicitly not designed for production environments. It is known to leak memory under most conditions and does not scale past a single process, making it suitable only for debugging and development.
fix
Implement a production-ready session store, such as `connect-redis`, `connect-mongo`, `memorystore`, or other compatible solutions listed in the `express-session` documentation.
affects: >=1.0.0
gotchaSince version 1.5.0, `express-session` directly reads and writes cookies on `req`/`res`. Using `cookie-parser` middleware concurrently can lead to issues, especially if the `secret` used by `express-session` differs from that used by `cookie-parser`.
fix
Generally, remove `cookie-parser` if `express-session` is handling session cookies. If `cookie-parser` is required for other (non-session) cookies, ensure that both middlewares use the *same* `secret` key.
affects: >=1.5.0
gotchaWhen configuring cookie options, if both `expires` and `maxAge` are set, the last one defined in the `cookie` object will take precedence. It is generally recommended to use only `maxAge`.
fix
Consistently use `maxAge` (in milliseconds) for controlling cookie expiration, and avoid setting `expires` directly.
affects: >=1.0.0
deprecatedThe `resave` option's default value of `true` has been deprecated and will change in future versions. Setting `resave: true` can create race conditions in certain session stores.
fix
Explicitly set `resave` to `false` unless your session store specifically requires it. Most modern stores handle session modifications efficiently without needing `resave: true`.
affects: >=1.0.0
breakingThe `cookie` dependency was updated to `0.6.0` in `express-session` v1.18.0, which included a fix to reject invalid dates for the `expires` option. Applications that might have implicitly handled or passed malformed dates to `expires` could experience errors.
fix
Ensure that any dynamically generated or configured `expires` dates are valid `Date` objects. It is best practice to use `maxAge` instead of `expires` for session cookies.
affects: >=1.18.0
gotchaSetting `cookie.httpOnly` to `false` (it defaults to `true`) allows client-side JavaScript to access the session cookie via `document.cookie`. This significantly increases the risk of Cross-Site Scripting (XSS) attacks leading to session hijacking.
fix
Always keep `cookie.httpOnly` set to `true` (the default) unless there is a very specific, well-understood requirement for client-side JavaScript to access the session cookie.
affects: >=1.0.0
Errors
Common errors & fixes
Error: secret must be a string or array of strings
The `secret` option, which is mandatory for session signing, was either omitted or provided with an invalid type (e.g., `null`, `undefined`, a number).
fix
Provide a strong, unpredictable string or an array of strings as the `secret` value in the `session()` options. It should be stored in an environment variable for security.
TypeError: session is not a function
This typically occurs when attempting to use `express-session` as a direct middleware function, rather than calling the imported module to get the middleware factory. This is often an ESM `import` or CommonJS `require` misuse.
fix
Ensure you are calling the imported `session` module to create the middleware: `app.use(session({ ... }))`. For CommonJS: `const session = require('express-session');`. For ESM: `import session from 'express-session';`.
Warning: connect.session() MemoryStore is not designed for a production environment, as it will leak memory, and will not scale past a single process.
This warning explicitly states that the default `MemoryStore` is being used in an environment that is likely production, which will lead to memory leaks and scalability issues.
fix
Replace the default `MemoryStore` with a production-grade, persistent session store like `connect-redis`, `connect-mongo`, or `memorystore`.
CookieParseError: Invalid cookie header
A conflict or misconfiguration between `express-session` and `cookie-parser`, particularly if both are used with different `secret` options, or if `cookie-parser` is used redundantly as `express-session` handles cookie parsing internally.
fix
Remove `cookie-parser` if `express-session` is sufficient for your cookie needs. If `cookie-parser` is still needed for other reasons, ensure both `express-session` and `cookie-parser` use the exact same `secret` value.
UnhandledPromiseRejectionWarning: Error: Bad session data
The session store returned corrupted or unparseable session data, or an internal error occurred during session deserialization. This can sometimes happen with store migrations or data integrity issues.
fix
Inspect the session store for malformed data. If using a custom store, verify its `get` and `set` methods. If using an existing store, check for recent updates to `express-session` or the store implementation that might address data handling bugs.
Upgrade
Version history
1.19.0latest on npm
Audit
Dependencies
expressrequiredThis package is middleware for the Express.js framework.
Agent activity
21 hits · last 30 days
node
18
OpenAI (training)
1
Resources
express-session — npm install express-session · libregistry