express-socket.io-session

1.3.5 verified Sat Apr 25 auth: no javascript maintenance

Share a cookie-based express-session middleware with socket.io. Works with Express >=4.0.0 and socket.io >=1.0.0. The current stable version is 1.3.5, released 2018-07-07, with no further updates expected (last release over 6 years ago). It provides access to the Express session object via socket.handshake.session. Key differentiator: simple drop-in middleware that reuses the same express-session instance, avoiding the need for a separate session store. Alternative approaches include using JWT or custom middleware with socket.io's own session management.

Common errors

error TypeError: session is not a function ↓

cause Passed the express-session module directly instead of calling it as a function

fix

const session = require('express-session')({ secret: 'keyboard cat', resave: true, saveUninitialized: true });

error socket.handshake.session is undefined ↓

cause Session middleware not applied to socket.io or applied before socket.io connection

fix

Ensure io.use(sharedsession(session)); is called before io.on('connection', ...).

error Cannot read property 'session' of undefined ↓

cause Accessing socket.handshake.session on a socket that doesn't have handshake (e.g., before middleware runs)

fix

Access session inside socket event handlers after connection; if using namespaces, ensure sharedsession is applied to the namespace as well.

error Module not found: Can't resolve 'express-socket.io-session' ↓

cause Package not installed or incorrectly imported in a browser environment

fix

npm install express-socket.io-session (server-side only; not a client-side package).

error TypeError: socket.handshake.session.save is not a function ↓

cause autoSave not enabled and session.save() not available unless using express-session's save method (require manual save)

fix

Enable autoSave: true or use socket.handshake.session.save() after modifications (only available after session middleware runs).

Warnings

breaking Requires express-session instance, not the module itself ↓

fix Pass the result of calling express-session() (the middleware function), not the express-session module.

deprecated autoSave option is false by default; session data not saved automatically ↓

fix Set autoSave: true in options or call socket.handshake.session.save() explicitly after modifications.

gotcha Session object is on socket.handshake.session, not socket.session ↓

fix Always access session via socket.handshake.session.

gotcha Only works with cookie-based sessions (express-session default store); custom stores may require extra configuration ↓

fix If using a custom session store, ensure it is compatible with express-session's save/load mechanisms.

breaking Not compatible with socket.io v3+ because socket.io v3 changed middleware signature ↓

fix Use socket.io <3 or find another solution for sharing sessions (e.g., socket.io v3 emits socket instead of next function).

Install

npm install express-socket.io-session

yarn add express-socket.io-session

pnpm add express-socket.io-session

Imports

default

wrong

const sharedsession = require('express-socket.io-session')

correct

import sharedsession from 'express-socket.io-session'

Package provides a CommonJS default export; using ESM import works due to Node.js interop.

sharedsession

wrong

const { sharedsession } = require('express-socket.io-session')

correct

const sharedsession = require('express-socket.io-session')

Default export, not named. Named import will be undefined.

express-session
wrong
```
const session = require('express-session').default
```
correct
```
import session from 'express-session'
```
express-session is a CommonJS module; both require and import work. Ensure session is configured before passing to express-socket.io-session.

Quickstart

Sets up Express with express-session and socket.io, sharing the session via express-socket.io-session. Shows session access in both HTTP and socket.io handlers.

const express = require('express');
const http = require('http');
const socketIO = require('socket.io');
const session = require('express-session');
const sharedsession = require('express-socket.io-session');

const app = express();
const server = http.createServer(app);
const io = socketIO(server);

const sessionMiddleware = session({
  secret: 'my-secret',
  resave: true,
  saveUninitialized: true
});

app.use(sessionMiddleware);
io.use(sharedsession(sessionMiddleware, { autoSave: true }));

app.get('/', (req, res) => {
  req.session.visits = (req.session.visits || 0) + 1;
  res.send('Session visit count: ' + req.session.visits);
});

io.on('connection', (socket) => {
  console.log('Socket connected. Session ID:', socket.handshake.session.id);
  socket.on('set-data', (data) => {
    socket.handshake.session.data = data;
    socket.handshake.session.save();
  });
  socket.on('get-data', () => {
    socket.emit('data', socket.handshake.session.data || null);
  });
});

server.listen(3000, () => console.log('Server listening on port 3000'));