{"id":18359,"library":"express-socket.io-session","title":"express-socket.io-session","description":"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.","status":"maintenance","version":"1.3.5","language":"javascript","source_language":"en","source_url":"https://github.com/oskosk/express-socket.io-session","tags":["javascript","socket.io","express","express-session"],"install":[{"cmd":"npm install express-socket.io-session","lang":"bash","label":"npm"},{"cmd":"yarn add express-socket.io-session","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-socket.io-session","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; the shared session middleware wraps an express-session instance","package":"express-session","optional":false}],"imports":[{"note":"Package provides a CommonJS default export; using ESM import works due to Node.js interop.","wrong":"const sharedsession = require('express-socket.io-session')","symbol":"default","correct":"import sharedsession from 'express-socket.io-session'"},{"note":"Default export, not named. Named import will be undefined.","wrong":"const { sharedsession } = require('express-socket.io-session')","symbol":"sharedsession","correct":"const sharedsession = require('express-socket.io-session')"},{"note":"express-session is a CommonJS module; both require and import work. Ensure session is configured before passing to express-socket.io-session.","wrong":"const session = require('express-session').default","symbol":"express-session","correct":"import session from 'express-session'"}],"quickstart":{"code":"const express = require('express');\nconst http = require('http');\nconst socketIO = require('socket.io');\nconst session = require('express-session');\nconst sharedsession = require('express-socket.io-session');\n\nconst app = express();\nconst server = http.createServer(app);\nconst io = socketIO(server);\n\nconst sessionMiddleware = session({\n  secret: 'my-secret',\n  resave: true,\n  saveUninitialized: true\n});\n\napp.use(sessionMiddleware);\nio.use(sharedsession(sessionMiddleware, { autoSave: true }));\n\napp.get('/', (req, res) => {\n  req.session.visits = (req.session.visits || 0) + 1;\n  res.send('Session visit count: ' + req.session.visits);\n});\n\nio.on('connection', (socket) => {\n  console.log('Socket connected. Session ID:', socket.handshake.session.id);\n  socket.on('set-data', (data) => {\n    socket.handshake.session.data = data;\n    socket.handshake.session.save();\n  });\n  socket.on('get-data', () => {\n    socket.emit('data', socket.handshake.session.data || null);\n  });\n});\n\nserver.listen(3000, () => console.log('Server listening on port 3000'));","lang":"javascript","description":"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."},"warnings":[{"fix":"Pass the result of calling express-session() (the middleware function), not the express-session module.","message":"Requires express-session instance, not the module itself","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Set autoSave: true in options or call socket.handshake.session.save() explicitly after modifications.","message":"autoSave option is false by default; session data not saved automatically","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Always access session via socket.handshake.session.","message":"Session object is on socket.handshake.session, not socket.session","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If using a custom session store, ensure it is compatible with express-session's save/load mechanisms.","message":"Only works with cookie-based sessions (express-session default store); custom stores may require extra configuration","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use socket.io <3 or find another solution for sharing sessions (e.g., socket.io v3 emits socket instead of next function).","message":"Not compatible with socket.io v3+ because socket.io v3 changed middleware signature","severity":"breaking","affected_versions":">=1.3.5"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"const session = require('express-session')({ secret: 'keyboard cat', resave: true, saveUninitialized: true });","cause":"Passed the express-session module directly instead of calling it as a function","error":"TypeError: session is not a function"},{"fix":"Ensure io.use(sharedsession(session)); is called before io.on('connection', ...).","cause":"Session middleware not applied to socket.io or applied before socket.io connection","error":"socket.handshake.session is undefined"},{"fix":"Access session inside socket event handlers after connection; if using namespaces, ensure sharedsession is applied to the namespace as well.","cause":"Accessing socket.handshake.session on a socket that doesn't have handshake (e.g., before middleware runs)","error":"Cannot read property 'session' of undefined"},{"fix":"npm install express-socket.io-session (server-side only; not a client-side package).","cause":"Package not installed or incorrectly imported in a browser environment","error":"Module not found: Can't resolve 'express-socket.io-session'"},{"fix":"Enable autoSave: true or use socket.handshake.session.save() after modifications (only available after session middleware runs).","cause":"autoSave not enabled and session.save() not available unless using express-session's save method (require manual save)","error":"TypeError: socket.handshake.session.save is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}