The Streamr Network monorepo publishes one version across every package

What is in the monorepo, user-facing and internal

The repository is a monorepo containing the main components of the Streamr Network, and the README splits them into two groups. The user-facing packages are `node` published as `@streamr/node`, `sdk` published as `@streamr/sdk`, and `cli-tools` published as `@streamr/cli-tools`. The internal packages are the working parts behind them: `utils` and `test-utils`, `proto-rpc` for the protocol buffer RPC layer, `browser-test-runner`, `autocertifier-client` and `autocertifier-server` for the certificate and identity machinery, `dht` for the distributed hash table, and `trackerless-network` for the peer discovery that does not rely on a central tracker. The topics list the shape of the system: decentralized, peer-to-peer, protocol, pubsub and streamr-client. The distinction matters if you are evaluating what to depend on, because a consumer normally takes the sdk or the node, and the internal packages exist so that those two can be built and versioned together rather than as independent downloads.

The bootstrap rule and why the sub-package directories are off limits

The workspace is managed with npm workspaces, and the README states one instruction in bold before listing the commands: do not use `npm ci` or `npm install` directly in the sub-package directories. The reason is the linking model. A monorepo of this kind links sibling packages into each other through the workspace, and running an install inside one sub-package bypasses that, producing a half-linked tree where a package resolves a sibling from the registry instead of from the working copy. The consequence is that you get two versions of the same code in one process. The go-to command for most cases is a single bootstrap from the top level, which installs all required dependencies and builds all sub-packages, linking them together as needed.

# from top level
npm run bootstrap

To do one package instead of all of them, there is a targeted variant.

# from top level
npm run bootstrap-pkg --package=$PACKAGE_NAME

And to install and link without the build phase, plain `npm ci` from the top level is enough.

Build, clean and the two kinds of cleanup

Building follows the same top-level convention, and there are two cleanup commands with different scopes, which is a distinction worth getting right before you run the wrong one. Building everything and building one package are separate scripts.

# from top level
npm run build

# from top level
npm run build --workspace=$PACKAGE_NAME

`clean-dist` clears all caches and removes the `dist` directory from each sub-package, while `clean` goes further and removes the `node_modules` of each sub-package along with the top-level `node_modules`. The manifest shows how the second one is composed, as a `clean-dist` call followed by a workspace-wide removal of `node_modules`, which is why the two are not interchangeable. There is a third recovery path for when the lock file itself has drifted. To regenerate `package-lock.json` from scratch you clean, remove `node_modules`, remove the lock file, clear the npm cache and reinstall.

npm run clean
rm -rf node_modules
rm package-lock.json
npm cache clean --force
npm install

The versions command is a real consistency check

One script in the manifest is more interesting than it looks. `npm run versions` runs `manypkg check` followed by a custom script, and the README explains what it prints: sub-packages and their versions on the left, linked sub-packages as columns, and if the package on the left links to the package in the column it shows a checkmark and the semver range, otherwise it shows the mismatched semver range and prints a warning at the end. It prints the version ranges so you can double-check they are formatted as you expect, with the example given being `^X.Y.Z` against `X.Y.Z`. The reason this matters is that a workspace with a dozen interdependent packages can drift into a state where the sdk expects a different range of the dht package than the dht package actually declares, and nothing fails loudly until runtime. The sibling script `fix-package-jsons` runs `manypkg fix`, so the check has a fixer. There is also `prune-pkg` for producing a production install of a single package.

Environment variables that reach across packages

The README documents a set of environment variables with the packages each one affects, and the table is a useful map of where the debugging levers are. `BROWSER_TEST_DEBUG_MODE` leaves the Electron window open while browser tests run, and it applies to utils, proto-rpc, dht, network-node and sdk. `STREAMR_DOCKER_DEV_HOST` sets an alternative IP address for streamr-docker-dev in end-to-end tests, for the sdk and node packages. The logging family is broader: `LOG_LEVEL` adjusts the log level across all packages, `DISABLE_PRETTY_LOG` prints JSONL instead of pretty output, `LOG_COLORS` turns off colouring, and `NOLOG` disables logging entirely, all of them applying to every package. `NODE_DATACHANNEL_LOG_LEVEL` adjusts the log level of the node-datachannel library, specifically for network-node, and `BUNDLE_ANALYSIS` produces a bundle analysis when building the sdk package for the browser, at compile time. There is also a wildcard `STREAMR__BROKER__` set of variables used to configure the node, documented in the node package's configuration page. Node.js version 22 is recommended.

The release process moves every package at once

All packages are released at the same time under the same version, and the release procedure is written out as three steps. The first is editing the changelog, which can be skipped for a beta, by creating a new section for the new version and moving items out of Unreleased. The second is creating and pushing the version and tag, and the commands matter because they enforce the uniformity.

git checkout main
git pull
./update-versions.sh <SEMVER>                                        # e.g. ./update-versions.sh 7.1.1
npm run clean && npm install && npm run build && npm run versions    # Check that the output has not red or yellow markers
git add -p .                                                         # or "git add -all"
./release-git-tags.sh <SEMVER>                                       # e.g. `./release-git-tags.sh 7.1.1`

Note the middle line, which runs the versions check and tells you to confirm the output has no red or yellow markers before staging anything. The third step is publishing the npm packages and the Docker image, and it waits for all tests to pass in GitHub Actions first, then uses the publish-npm workflow. The repository carries `release.sh` and `release-git-tags.sh` alongside `update-versions.sh`, a `lerna.json`, a `Dockerfile.node` and per-target TypeScript configs for node, browser and jest, plus karma and a separate browser test runner package.

Editorial conclusion

Adopt the Streamr Network monorepo if you are building on the pubsub and peer-to-peer layer and want the node, sdk and DHT packages from one consistent build. Skip it if you only need to publish or subscribe through the hosted service, since the user-facing packages are published to npm on their own. Before you clone, read the install notes for Apple Silicon, and follow the bootstrap rule strictly: npm installs and npm ci are run from the top level, never inside a sub-package directory.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. streamr-dev/network on GitHub