Express Session Middleware

Common errors

• Error: secret must be a string or array of strings

  cause 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

  cause 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.

  cause 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

  cause 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

  cause 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.

Warnings

• gotcha The 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.
• gotcha Since 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.
• gotcha When 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.
• deprecated The `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`.
• breaking The `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.
• gotcha Setting `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.

Install

• npm install express-session npm
• yarn add express-session yarn
• pnpm add express-session pnpm

Imports

• session
  wrong:

  import { session } from 'express-session'

  correct:

  import session from 'express-session'

  The primary export is a default function that creates the middleware.
• session
  wrong:

  const { session } = require('express-session')

  correct:

  const session = require('express-session')

  CommonJS require imports the default middleware factory function.
• SessionStore
  wrong:

  import { SessionStore } from 'express-session'; // Incorrect export name for type

  correct:

  import { Store } from 'express-session'; // For type hinting custom stores

  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.

Quickstart

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.');
});