Registry /
http-networking / socket.io-express-session
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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ios
✓ const ios = require('socket.io-express-session');
✗ import ios from 'socket.io-express-session';
This package only supports CommonJS `require()` syntax due to its age (last published 2015). ESM `import` will result in an error.
ios (main function)
✓ const connectSession = require('socket.io-express-session');
✗ const { connectSession } = require('socket.io-express-session');
The package exports a single function as its default/module.exports. Destructuring named exports is incorrect.
ios (TypeScript)
✓ /// <reference types="node" />
// No official TypeScript types exist, manual declaration or @types/module-name might be needed for older packages.
✗ import { SessionMiddleware } from 'socket.io-express-session';
There are no official or community-maintained TypeScript types for this package. It was published before widespread TypeScript adoption in the Node.js ecosystem.
This quickstart demonstrates how to set up `socket.io-express-session` to share Express sessions with Socket.IO connections, allowing access to `socket.handshake.session`. It includes basic Express and Socket.IO server initialization and highlights session access within Socket.IO connection handlers.
const express = require('express');
const { createServer } = require('http');
const session = require('express-session');
const { Server } = require('socket.io');
const ioSession = require('socket.io-express-session'); // The package being documented
const app = express();
const httpServer = createServer(app);
const io = new Server(httpServer);
// IMPORTANT: Use a production-ready session store, not MemoryStore for production.
const sessionMiddleware = session({
secret: 'my-super-secret-key-that-should-be-long-and-random',
resave: false,
saveUninitialized: true,
// store: new (require('connect-redis')(session))({ client: require('redis').createClient() })
});
app.use(sessionMiddleware);
// Integrate express-session with Socket.IO
io.use(ioSession(sessionMiddleware));
io.on('connection', (socket) => {
console.log('A user connected:', socket.id);
// Access the session from the handshake object
const userSession = socket.handshake.session;
if (userSession) {
console.log('Session data on connection:', userSession);
userSession.views = (userSession.views || 0) + 1;
console.log('Updated views:', userSession.views);
// In older packages, you might need to manually save if 'autoSave' isn't configured/available.
// userSession.save(); // Not explicitly mentioned as needed by this package
}
socket.on('disconnect', () => {
console.log('User disconnected:', socket.id);
});
});
app.get('/', (req, res) => {
req.session.pageViews = (req.session.pageViews || 0) + 1;
res.send(`Hello from Express! Page views: ${req.session.pageViews}`);
});
const PORT = process.env.PORT || 3000;
httpServer.listen(PORT, () => {
console.log(`Server running on http://localhost:${PORT}`);
});
Debug
Known issues
breakingThe package is over 10 years old and has been abandoned. It is not compatible with modern ES Modules (ESM) syntax and may have severe compatibility issues or security vulnerabilities with current versions of Node.js, Socket.IO, or Express.js.fixMigrate to a more modern solution. The official Socket.IO documentation provides direct examples of integrating `express-session` using `io.use(sessionMiddleware)` or `io.engine.use(sessionMiddleware)` without relying on this deprecated package.
affects: All versions
gotchaUsing the default `MemoryStore` for `express-session` in a production environment is strongly discouraged. It can lead to memory leaks and will not scale across multiple process instances or servers, causing inconsistent session data.fixAlways configure `express-session` with a persistent, production-ready session store like Redis (`connect-redis`), MongoDB (`connect-mongo`), or a database-backed store for any non-trivial application. Ensure the store is accessible by all Node.js instances if scaling horizontally.
affects: All versions
gotchaIt is critical to pass the *exact same* `express-session` configuration (including the `store`, `secret`, and other options) to both your Express application and the `socket.io-express-session` middleware. Mismatched configurations will result in session data not being shared or incorrect session identification.fixDeclare your `express-session` middleware once with all its configuration, and then pass that *instance* of the middleware to both `app.use()` and `io.use(ioSession(...))`.
affects: All versions
deprecated`express-session` itself has deprecated the `undefined resave option` and `undefined saveUninitialized` options. While not directly a `socket.io-express-session` warning, using an old version of `express-session` with this middleware could lead to warnings or unexpected behavior if these options are not explicitly set.fixEnsure `resave` and `saveUninitialized` are explicitly set to `true` or `false` in your `express-session` configuration. For new projects, use modern `express-session` versions and the recommended direct integration patterns.
affects: <=0.1.3 (indirectly via `express-session` versions used)
Errors
Common errors & fixes
TypeError: require(...) is not a function
Attempting to use ES Module `import` syntax (`import ioSession from 'socket.io-express-session';`) for this CommonJS-only package, or misinterpreting its export.
fixUse CommonJS `require` syntax: `const ioSession = require('socket.io-express-session');`. TypeError: Cannot read properties of undefined (reading 'session') when accessing socket.handshake.session
This error typically occurs if the `socket.io-express-session` middleware was not correctly applied to the Socket.IO instance (`io.use(ios(session))`) or if the `express-session` configuration itself is not correctly initialized or shared. It can also happen if the client does not send the session cookie.
fixVerify that `io.use(ioSession(sessionMiddleware))` is called after `sessionMiddleware` is defined and `app.use(sessionMiddleware)` is set up. Ensure client-side `socket.io-client` connections are configured with `withCredentials: true` if cookies are expected to be sent. Double-check that `secret`, `store`, and other critical session options are identical between Express and Socket.IO setups.
Session data not persisting across Socket.IO reconnections or page refreshes.
This is often due to using the default `MemoryStore` in a multi-process or scaled environment, or if the `secret` key or session `store` instance is not identical between Express and Socket.IO, leading to new sessions being created. Cross-origin issues without proper CORS configuration can also cause this.
fixMigrate from `MemoryStore` to a production-ready session store (e.g., Redis). Ensure the *same instance* of the session configuration (especially `secret` and `store`) is passed to both Express and Socket.IO. For cross-origin setups, configure CORS headers appropriately on your server and `withCredentials: true` on the Socket.IO client.
Audit
Dependencies
express-sessionrequiredRequired to provide the session management that this middleware integrates with Socket.IO.
socket.iorequiredThe core real-time communication library that this middleware extends to share sessions.