refactor [NET-1606]: Bundle utils separately for browser and NodeJS

[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 for first-class browser and Node.js support with dual bundles, conditional exports, and polyfilled APIs.

• New Rollup config (packages/utils/rollup.config.mts) outputs exports-browser.* and exports-nodejs.*; package.json uses conditional exports and updated build scripts
• Introduces env/crypto platform shims: src/nodejs/{env,crypto}.ts and src/browser/{env,crypto,os}.ts; removes src/crossPlatformCrypto.ts
• Replaces Node-only APIs with cross-platform imports: Logger reads from @/env; hashing via computeMd5; updated SigningUtil to use @/crypto
• Adds browser entry src/exports-browser.ts (includes buffer-shim) and path aliases for both envs; updates Jest/Karma configs and tsconfigs (tsconfig.{node,browser,jest,karma}.json)
• Updates packages/utils/package.json fields (main/module/types, files) and dependencies (Rollup, plugins, polyfills)
• Docker build now bootstraps @streamr/utils in Dockerfile.node

^{Written by Cursor Bugbot for commit b3774ce. 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.