Use Bun Workspaces with Nx

A Bun workspace lets you manage multiple packages in a single repository. Adding Nx to a Bun workspace gives you cached tasks, affected-only builds, and faster CI, while Bun keeps managing installs. This recipe sets up a Bun workspace and then adds Nx.

Set up a Bun workspace

A Bun workspace is a repository whose root package.json has a workspaces field listing the directories that hold package.json files:

package.json

{
  "name": "my-workspace",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
}

A common layout separates applications from shared packages:

• Directorymy-workspace/

  • Directoryapps/

    • Directoryweb/

      • package.json
  • Directorypackages/

    • Directoryshared-ui/

      • package.json
  • package.json

To depend on another package in the workspace, reference it with the workspace: protocol so Bun resolves it to the local package:

apps/web/package.json

{
  "name": "web",
  "dependencies": {
    "react": "^19.0.0",
    "@my-workspace/shared-ui": "workspace:*",
  },
}

Run bun install once at the root to install every package's dependencies and link the internal ones.

Add Nx in one command

Nx layers task running and caching on top of your existing Bun workspace. Bun still installs and resolves packages; Nx makes your tasks cacheable and your CI affected-aware. Add it with one command, which works on any npm, Yarn, pnpm, or Bun workspace:

npx nx@latest init

Your existing package.json scripts keep working. Nx infers a project for each package.json in your workspace and runs its scripts with caching, with no project.json or extra configuration required.

Run tasks before and after Nx

Before Nx, Bun runs a script across packages, but it runs every task every time and has no notion of which packages a change affects. Place --filter before the script:

bun run --filter '*' build   # every package
bun run --filter web build   # a single package

After nx init, run the same scripts through Nx:

nx run-many -t build   # every project
nx build web           # a single project
nx affected -t build   # only projects touched by your changes

The first run executes your scripts. A second run with no changes is restored from the cache instantly, and nx affected skips the projects your change does not touch.

How task caching works

nx init writes an nx.json with targetDefaults that control which targets are cached:

nx.json

{
  "targetDefaults": {
    "build": {
      "cache": true,
      "dependsOn": ["^build"],
    },
  },
}

cache: true makes a target cacheable: Nx hashes each project's inputs (source files, dependencies, and config) and restores its outputs from the cache when nothing has changed. dependsOn: ["^build"] builds a project's dependencies first. Nothing is cached unless you opt in, so you stay in control.

In CI, turn on remote caching and task distribution to share the cache across machines and parallelize tasks. For a deeper walkthrough, see Adding Nx to an NPM/Yarn/PNPM Workspace.