nx-bun-integration

Nx Bun Integration

Navigation hub for integrating Bun into Nx workspaces.

When to Use

• You are adding Bun projects to an existing Nx workspace.
• You are converting Node.js projects to Bun executors.
• You need cache-aware build, run, and test targets with @nx-bun/nx.
• You need predictable migration guidance for package-manager and runtime changes.

When Not to Use

• The task is Bun runtime API usage without Nx integration concerns.
• The workspace is intentionally standardized on Node.js executors only.

Workflow

1. Install @nx-bun/nx and initialize the plugin.
2. Generate or convert projects to Bun executors.
3. Configure cache inputs and outputs for build/test targets.
4. Validate serve, build, and test on one project: run nx build my-api && nx test my-api && nx serve my-api and confirm all three exit with code 0 before proceeding. If validation fails: check executor configuration in project.json, run nx reset to clear stale cache, and retry. Resolve all failures before rolling out.
5. Roll out to affected projects and enforce anti-pattern checks.

Quick Commands

Install and Initialize Plugin

bun add -D @nx-bun/nx
nx g @nx-bun/nx:init --unitTestRunner=bun

Expected: plugin is installed and generators/executors are available.

Generate Bun Application

nx g @nx-bun/nx:application api --directory=apps/backend --tags=runtime:bun,type:app

Expected: Bun-ready app with Nx project configuration.

Convert Existing Project

nx g @nx-bun/nx:convert-to-bun --project=my-api

Expected: project targets move to Bun executors while preserving Nx target structure.

Verify Build/Test/Run

nx build my-api
nx test my-api
nx serve my-api

Expected: build outputs generated, tests run under Bun test runner, serve target starts.

Run Affected in CI-style

bun nx affected -t lint,test,build --base=main --parallel=3

Expected: only changed projects execute with Nx scheduling.