Skip to main content

Socket.IO monorepo

· 3 min read
Damien Arrachequesne

Hello everyone!

We are happy to announce that the Socket.IO codebase has been merged into a monorepo.

note

A monorepo is a single repository containing multiple distinct projects, with well-defined relationships.

More info here

Modular architecture​

As part of the work towards v1.0 ten years ago (!), the Socket.IO codebase was split into several packages, each with its own responsibility:

Diagram of the package inter-dependencies

At the time, tools like lerna or pnpm workspaces that make it easier to develop and publish multiple JavaScript packages from the same repository did not exist yet, so the codebase was split into multiple GitHub repositories:

However, this structure has several downsides:

  • it's harder for newcomers to dig into the codebase and understand what's going on under the hood
  • a change that affects multiple repositories is more difficult to test
  • mundane tasks like configuring CI or updating development dependencies must be replicated across all repositories

That's why we have made the decision to merge all repositories into a single one. The source codes for the different packages are now located in the packages/ directory:

packages/
├── engine.io
├── engine.io-client
├── engine.io-parser
├── socket.io
├── socket.io-adapter
├── socket.io-client
└── socket.io-parser

Workspaces​

To manage the packages, we use npm workspaces which were introduced in npm v7 (bundled with Node.js v15). The package.json file at the root of the repository lists all packages and their development dependencies:

package.json
{
  "private": true,
  "workspaces": [
    "packages/engine.io-parser",
    "packages/engine.io",
    "packages/engine.io-client",
    "packages/socket.io-adapter",
    "packages/socket.io-parser",
    "packages/socket.io-client",
    "packages/socket.io"
  ],
  "devDependencies": {
    // [...]
  }
}

After cloning the repository, running npm install will fetch all necessary dependencies and create the links between the packages:

$ npm ls
socket.io@ /git/socket.io
└─┬ socket.io@4.7.5 -> ./packages/socket.io
  ├── accepts@1.3.8
  ├── base64id@2.0.0
  ├── cors@2.8.5
  ├── debug@4.3.5
  ├── engine.io@6.6.0 -> ./packages/engine.io
  ├─┬ socket.io-adapter@2.5.5 -> ./packages/socket.io-adapter
  │ ├── debug@4.3.5 deduped
  │ └── ws@8.17.1 overridden
  └─┬ socket.io-parser@4.2.4 -> ./packages/socket.io-parser
    ├── @socket.io/component-emitter@3.1.2 -> ./packages/socket.io-component-emitter
    └── debug@4.3.5 deduped

And finally, running npm test --workspaces (or npm test -ws) will run the tests on all workspaces, ensuring that any change is properly tested over the whole codebase.

tip

Our contributing guide has been updated accordingly.

Git history​

Obviously, losing 10 years of git history from the other repositories was not an option. The repositories have thus been merged with the --allow-unrelated-histories option, in order to include their history in the monorepo:

Schema of the preserved git history

Reference: https://git-scm.com/docs/git-merge#Documentation/git-merge.txt---allow-unrelated-histories

GitHub issues​

Similarly, it was not conceivable to lose the list of open GitHub issues across all repositories, since it is our most valuable source of user feedback, so they have been moved to the main repository: https://github.com/socketio/socket.io/issues

Hopefully, this change should make it easier for anyone to contribute to the project in the future.

That's all folks, thanks for reading!