Socket.IO: twelve workspaces, mixed version numbers, one private root

The root package.json is private, so the repo root is not the package

The manifest at the repository root sets name to socket.io and private to true, then lists twelve workspace paths under packages/. Those two lines together mean the root manifest is a monorepo container: it exists to resolve the workspace tree, and it is explicitly marked as not publishable. The published artifact behind the README's npm badge is the socket.io package, and inside this tree that package sits at packages/socket.io. So the first thing to settle before you clone anything is that an install at the repository root resolves all twelve workspaces at once, devDependencies included, because the root manifest is where the workspace list and the overrides live. There is no root package here you can add to a project. For a reader who wants the library, that is a signal to take the package from the npm page the badge points at and leave the repository alone.

Twelve workspaces, and version numbers that do not line up

The workspace list reads socket.io-component-emitter, engine.io-parser, engine.io, socket.io-cluster-engine, engine.io-client, socket.io-adapter, socket.io-cluster-adapter, socket.io-parser, socket.io-client, socket.io, socket.io-postgres-emitter and socket.io-redis-streams-emitter. The names give you the shape of the system: a server package and a client package, a parser for the engine layer plus a client counterpart of it, an adapter pair for shared state, and two emitter packages bound to external stores, one for Postgres and one for Redis Streams. Now look at the release feed, because the numbers do not line up. socket.io went out as 4.8.4 and socket.io-client also went out as 4.8.4, while engine.io-client shipped on the same morning as 6.6.7. Consequence: there is no single version number for Socket.IO. A ticket saying upgrade to 4.8.4 tells you nothing about the transport underneath, and pinning one of these packages in a lockfile pins none of the others.

The overrides block pins ws and two type packages, and only inside this tree

The root manifest carries an overrides block fixing @types/estree to 0.0.52, @types/lodash to 4.14.189 and ws to 8.21.0, each written without a caret. That block exists so every workspace resolves identical copies.. The trap is where the constraint takes effect. npm overrides apply to the tree installed from this root manifest, not to an application that adds socket.io from the registry. Copying 8.21.0 into your own package.json does not reproduce the workspace resolution, it just hard-pins one dependency in your project on your own authority. If you need the same guarantee, you write the override yourself, and the value to copy is 8.21.0 rather than whatever your other packages happen to resolve.

Usage questions are routed away from the issue tracker by policy

The README states that the issues list is reserved for bug reports and feature requests, then names four places for everything else: the documentation at socket.io/docs/v4/, a troubleshooting guide for connection issues, a Stack Overflow tag, and a new GitHub discussion under the q-a category. Security has a separate route. The instruction is to refer to SECURITY.md instead of opening an issue in the repository when you believe you have found a vulnerability. What this means for you is that the tracker is not a support channel, and it will not be a place to ask how to attach a client. The README's only usage instruction is to check the documentation, so a connection that will not open sends you to the troubleshooting page first. The cost is a round trip outside the repository for the questions a readme usually answers.

The examples directory is the only in-repo usage reference

With a README that stops at a documentation link, the examples folder carries the actual shape of the API. It holds chat, basic-crud-application, basic-websocket-client, custom-parsers, es-modules, express-session-example, http2-example and connection-state-recovery-example, then the framework and platform directories: angular-todomvc, create-react-app-example, nestjs-example, nuxt-example, nwjs-example, expo-example, ReactNativeExample, and two separate Next.js shapes in nextjs-app-router and nextjs-pages-router. Six more directories are named cluster-something, covering node-cluster, redis, haproxy, httpd, nginx and traefik. Two consequences. First, the framework list is a compatibility statement in directory form, and React appears twice over with the App Router and the Pages Router, so you have to know which Next.js routing model you are on before any of it applies to you. Second, when a connection fails behind a proxy, this tree hands you six deployment topologies to check and one troubleshooting page to check them against.

The visible dev toolchain reaches past Node into browsers and HTTP/3

The visible devDependencies describe a test setup that goes outside the Node process. There is @wdio/cli with @wdio/local-runner, @wdio/mocha-framework, @wdio/sauce-service and @wdio/spec-reporter, which is a WebDriverIO matrix able to run against Sauce, plus @fails-components/webtransport and @fails-components/webtransport-transport-http3-quiche for HTTP/3 work, alongside eiows and @sinonjs/fake-timers for controlling time. That is a wide test surface.

package-lock.json is the workspace's ground truth, not a consumer's version list

The root listing carries package-lock.json, CHANGELOG.md, CONTRIBUTING.md, SECURITY.md, LICENSE, docs/, examples/, packages/ and a .github directory. LICENSE is MIT. The lockfile is there because this is a twelve-workspace tree running its own overrides, and a lockfile for a tree nobody publishes tells you what the maintainers resolve locally, not what you will resolve when you install socket.io from the registry: your build sees the library's own declared ranges, not this file. The change record has the same problem. CHANGELOG.md exists and nothing links to it, so the route from a release number to its notes is a guess. CONTRIBUTING.md is the one file the readme does point to, for anyone opening an issue or sending a pull request. Maintenance itself is current: the last push to main landed on 2026-09-29, and [email protected], [email protected] and [email protected] were published that morning.

Editorial conclusion

Use Socket.IO when you need bidirectional messaging across browsers, React Native, Expo, Next.js, Nuxt, NestJS and NW.js, and especially when several nodes have to fan out one event, since the tree ships adapters and a Postgres and Redis Streams emitter. Stay on a plain WebSocket when traffic is one way and you do not want a second layer. Check three things first: which package you actually need, because the release feed carries [email protected] and [email protected] on the same morning, which Node version your runtime matches,, and whether you will run behind a proxy, because the repository ships six cluster topologies. The real decision is not the API surface, it is how many packages you are agreeing to pin.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes