refactor [NET-1606]: Make utils package work without polyfilling

[mondoreale]

This pull request introduces significant improvements to the @streamr/utils package, focusing on robust browser and Node.js environment support, build configuration enhancements, and codebase modernization. The main changes include a new dual build and export system for browser and Node.js, environment variable handling refactoring, and the replacement of Node.js-specific APIs with cross-platform polyfills.

Changes

Build and packaging enhancements:

• Added a dual build system using a new rollup.config.mts to generate separate browser and Node.js bundles, with appropriate module resolution and aliasing for each environment. (packages/utils/rollup.config.mts)
• Updated package.json to use the exports field for conditional exports (browser vs. Node.js), adjusted the files array, and added new build scripts and dependencies for Rollup and polyfills. (packages/utils/package.json) [1] [2]
• Introduced a prebuild and postbuild step to streamline the build process and ensure clean output. (packages/utils/package.json)

Cross-platform and polyfill improvements:

• Replaced direct Node.js API usage (e.g., crypto, os) with cross-platform abstractions and browser polyfills (e.g., buffer-shim, path-browserify, custom os and env shims for browsers). (packages/utils/src/browser/crypto.ts, packages/utils/src/browser/env.ts, packages/utils/src/browser/os.ts, packages/utils/src/exports-browser.ts, packages/utils/src/keyToArrayIndex.ts, packages/utils/karma.config.ts) [1] [2] [3] [4] [5] F8929faeL1)
• Removed the old crossPlatformCrypto.ts in favor of new environment-specific implementations. (packages/utils/src/crossPlatformCrypto.ts)

Environment variable handling:

• Refactored all environment variable access to use a unified env abstraction, ensuring safe access in both Node.js and browser contexts. (packages/utils/src/Logger.ts, packages/utils/src/browser/env.ts) [1] [2] [3] [4] [5] [6]

Testing and configuration:

• Updated Jest and Karma configurations to support new module aliases and environment-specific code paths. (packages/utils/jest.config.ts, packages/utils/karma.config.ts) (packages/utils/jest.config.tsL1-R11, F8929faeL1)

Code modernization and cleanup:

• Updated cryptographic utilities to use new cross-platform imports and types, improving maintainability and browser compatibility. (packages/utils/src/SigningUtil.ts, packages/utils/src/exports.ts) [1] [2] [3] [4] [5] [6] [7] [8] [9] [10]

Additional minor improvements:

• Added @streamr/utils to the Docker build bootstrap step. (Dockerfile.node)

These changes collectively make the @streamr/utils package more robust, easier to consume in different environments, and simpler to maintain.

---

Note

Modernizes @streamr/utils to be environment-agnostic with separate Node and browser builds and conditional exports.

• Introduces dual build pipeline via rollup.config.mts and package.json exports for browser/Node outputs
• Replaces Node-only APIs with cross-platform abstractions: new @/crypto, @/env, browser shims (buffer-shim, path-browserify, custom os), removes crossPlatformCrypto
• Refactors Logger, SigningUtil, keyToArrayIndex, and exports to use new env/crypto utilities
• Updates Jest/Karma and TS configs for path aliases and environment-specific sources; adds utils to Docker bootstrap

^{Written by Cursor Bugbot for commit ab28235. This will update automatically on new commits. Configure here.}

[linear]

NET-1606 `@streamr/utils` used in a Vite/webpack app requires polyfilling

[cursor]

This PR is being reviewed by Cursor Bugbot

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[cursor]

Browser env mutates global process.env object

Object.assign(defaultEnv, {...}) mutates process.env directly when it exists in polyfilled browser environments. If process.env is polyfilled (common with bundlers like Webpack), this adds DISABLE_PRETTY_LOG: 'true' to the global object, which could cause unexpected side effects for other code in the same bundle that checks this property. A safer approach would be to create a new object with spread syntax ({ ...defaultEnv, DISABLE_PRETTY_LOG: 'true' }) instead of mutating the source.