neverbun

⚠️ This project is for people who don't like Bun. If you like Bun, please go look at onlybun instead.

Traditional Chinese Readme

Import it once, and your program politely refuses to exist the moment it notices it's running on Bun. Zero dependencies, CJS and ESM, no opinions about anything else.

Install

npm install neverbun

Yes, with npm. That was rather the point.

Usage

Put this at the very top of your entry file and forget about it:

import 'neverbun';        // ESM
require('neverbun');      // CJS

On Node.js: absolutely nothing happens. That's the good ending.

On Bun:

  ✗ This project does not support Bun.

    Detected runtime: Bun v1.4.0
    Please use Node.js instead (e.g. `node`, `npm run`, `pnpm run`).

    To skip this check anyway: NEVERBUN_DISABLE=1

...followed immediately by process.exit(1). No negotiation, no grace period.

Two layers of defence

Because one layer would be complacent.

1. Module resolution. The exports map in package.json declares a "bun" condition pointing at src/unsupported.js. Bun walks confidently into a dead end before the real entry point is ever loaded.
2. Runtime detection. The entry points check process.versions.bun and the global Bun object on load. This catches bun --bun running a Node script, and every bundler that ignores export conditions (which, as it turns out, is most of them — see below).

API

If you'd rather not have an import that terminates your process — a reasonable preference — use neverbun/check. That subpath has no side effects whatsoever.

import { isBun, getBunVersion, assertNotBun, terminateIfBun } from 'neverbun/check';

isBun();            // boolean
getBunVersion();    // '1.4.0' | null
assertNotBun();     // throws on Bun (code: 'ERR_UNSUPPORTED_RUNTIME_BUN')
terminateIfBun({ message: 'Please run `node server.js`', exitCode: 2 });

The main entry point re-exports the same functions, it just also pulls the trigger on the way in.

Environment variables

| Variable | What it does | | --- | --- | | NEVERBUN_DISABLE=1 | The escape hatch. Disables the check entirely, even on Bun. | | NEVERBUN_EXIT_CODE | Exit code used when terminating. Defaults to 1. |

Where to put this in a framework project

The one rule: this package only helps when Bun actually executes that import. Bundlers bundle your app code, they don't run it — so putting the import in the wrong file buys you exactly nothing.

All of the following was measured, not guessed (Node v26 / Bun v1.4):

| Scenario | Bun | Node | | --- | --- | --- | | Plain Node script (require / import) | ✅ stopped, exit 1 | ✅ fine | | bun --bun script.js | ✅ stopped | — | | Import inside vite.config.js | ✅ stopped | ✅ fine | | Import in Vite app code, bun vite build | ❌ not stopped, build succeeds | ✅ fine | | Next.js server component, next build | ✅ stopped, exit 1 | ✅ exit 0 | | Astro page frontmatter, astro build | ✅ stopped, exit 1 | ✅ exit 0 | | Pure client-side code | ❌ pointless (browsers aren't Bun) | — |

Recommendation: put it in the config file

// vite.config.js / astro.config.mjs / next.config.mjs
import 'neverbun';
export default { /* ... */ };

Config files are always evaluated directly by whichever runtime is running the CLI, which makes them the one genuinely reliable spot. Next.js and Astro also catch it in app code, but only because they really do execute page modules during the build to do SSG. Vite's pure client-side app code never runs at build time, so nothing fires.

Two things worth knowing

• The "bun" export condition is only honoured by Bun's own resolver. Vite, webpack and Turbopack use their own condition lists, and "bun" isn't on them. Measured: bun vite build and node vite build produced an identical bundle hash, meaning the condition was never consulted and the runtime-detection layer is what did the work.
• Don't let it into a client bundle. It won't be tree-shaken (sideEffects is deliberately set to keep it), so you'd ship roughly 2.5 KB of dead code to a browser that was never going to be Bun in the first place.

Blocking everything

An import can't stop bun install, because by then it's too late. For total coverage, add one more layer in package.json:

{
  "scripts": {
    "preinstall": "node -e \"if(process.versions.bun)throw new Error('Use npm/pnpm, not bun')\""
  }
}

Tests

node test/run.cjs

This builds a real consumer fixture (with a node_modules symlink) and runs it under both Node and Bun. If Bun isn't installed locally, those tests are skipped — which is, admittedly, the ideal state of affairs.

Don't run this with npm test if you have alias npm=bun in your shell. Ask me how I know.

License

MIT