Using Bun Better with Nx: Migrating from Nx 18 to 21

The Fintech Group Frontend team has been using Nx as their monorepo management tool and Bun as their package manager. However, Nx 18.3.3 did not officially support Bun, and unexpected compatibility issues kept surfacing in actual operations.

The first problem encountered was nx migrate mistakenly identifying Yarn as the package manager. Because a yarn.lock file remained in the root, Nx selected Yarn, and since Yarn was not installed locally, the install step failed. They worked around this by temporarily removing yarn.lock only during migration, and moved to a flow that received official Bun support in Nx 19.5+.

The second problem was HookWebpackError: Cannot read properties of undefined (reading 'data'), which occurred when generatePackageJson: true was enabled in a webpack build. This was caused by the fact that, in the process of Nx reading the External Node metadata in the project graph to generate the package.json for build artifacts, it failed to properly parse the older Bun's bun.lockb (binary format).

Workarounds included switching to generatePackageJson: false or attaching a custom plugin, but these carried a significant maintenance burden. Since a Storybook 9 migration was already under review, and its minimum supported version was Nx 21.2, they ultimately decided it made more sense to upgrade to Bun 1.2.x to convert bun.lockb to bun.lock, and upgrade to Nx 21.4+.

This transition also resolved the binary constraints of bun.lockb. The problems of not being able to view PR diffs, difficult merge conflict resolution, and external tools struggling to parse the file all disappeared, and Nx's handling of Bun also stabilized. As a result, the CI pipeline was shortened from 13 minutes 30 seconds to 11 minutes 40 seconds, a reduction of about 14%, and artifact size decreased from 330MB to 280MB, a reduction of about 15%.

Beyond the quantitative improvements, the dual management of bun.lockb and yarn.lock was eliminated, and changes in Dependabot PRs became visible as text diffs. They also noted that when using officially unsupported combinations, one should check the support roadmap, related issues, lock file compatibility, and rollback plans in advance, and that proceeding with major upgrades rather than postponing them at each stabilization point is safer in the long run.