eslint-plugin-bunisms 🐰

ESLint rules for idiomatic and correct Bun code. Supports TypeScript and JavaScript, Oxlint, and ESLint 9–10.

Installation

bun add -D eslint-plugin-bunisms

You also need oxlint or eslint installed.

Oxlint

// oxlint.config.ts
import { defineConfig } from 'oxlint';

export default defineConfig({
  jsPlugins: [{ name: 'bun', specifier: 'eslint-plugin-bunisms' }],
  rules: {
    'bun/prefer-bun-file': 'warn',
    'bun/prefer-bun-write': 'warn',
    'bun/prefer-bun-spawn': 'warn',
    'bun/prefer-bun-crypto-hasher': 'warn',
    'bun/prefer-import-meta-path': 'warn',
    'bun/prefer-import-meta-dir': 'warn',
    'bun/prefer-import-meta-main': 'warn',
  },
});

ESLint is optional when using Oxlint. Oxlint's JavaScript plugin support is currently alpha; compatibility is tested in CI.

ESLint

// eslint.config.ts
import bun from 'eslint-plugin-bunisms';

export default [bun.configs.recommended];

ESLint needs jiti to load a TypeScript config file on Node. For TypeScript files, configure a TypeScript parser such as @typescript-eslint/parser. These rules do not require type information.

Rules

| Rule | Recommends | | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | bun/prefer-bun-file | Bun.file() instead of Node's readFile() | | bun/prefer-bun-write | Bun.write() instead of Node's writeFile() | | bun/prefer-bun-spawn | Bun.spawn() / Bun.spawnSync() instead of Node's subprocess equivalents | | bun/prefer-fetch | fetch() instead of Node HTTP client get() / request() (strict and all) | | bun/prefer-bun-crypto-hasher | Bun.CryptoHasher instead of supported createHash() chains | | bun/prefer-bun-shell | Bun Shell instead of shell-oriented exec() calls (strict and all) | | bun/prefer-import-meta-path | import.meta.path instead of fileURLToPath(import.meta.url) | | bun/prefer-import-meta-dir | import.meta.dir instead of dirname(fileURLToPath(import.meta.url)) | | bun/prefer-import-meta-main | import.meta.main instead of entrypoint comparisons | | bun/prefer-import-meta-resolve | Consider ESM module resolution with import.meta.resolve() (strict and all) | | bun/no-dotenv | Avoid redundant standard dotenv initialization when targeting Bun | | bun/no-late-module-mock | Warn when a static import can run before mock.module() (strict and all) |

Rules recognize imports, aliases and CommonJS bindings, respecting lexical scope. The exception is prefer-import-meta-resolve, which only checks direct global require.resolve() calls and skips CommonJS files. They report calls and entrypoint comparisons without automatically rewriting them. Review runtime compatibility and semantics before migrating.

The recommended, strict and all ESLint presets enable rules as warnings. prefer-bun-shell, prefer-fetch, prefer-import-meta-resolve and no-late-module-mock are limited to strict and all because shell behavior, HTTP client semantics, callback handling, module resolution semantics and module mock timing need deliberate migration. Override individual rules after the preset:

export default [bun.configs.recommended, { rules: { 'bun/prefer-bun-file': 'error' } }];

Compatibility

Targets Bun >=1.4.0 applications. The plugin itself runs on Node >=18.18.0, subject to your linter's Node requirements, and has no runtime dependencies.

Apply the plugin only to code intended for Bun. For a mixed-runtime project, scope the ESLint preset with files:

export default [{ ...bun.configs.recommended, files: ['scripts/**/*.ts'] }];

See Contributing for development, the roadmap for planned rules, and Versioning for the release policy.

See also

• @himynameisdave/oxlint-config
• @himynameisdave/oxfmt-config

MIT © Dave Lunny