esbuild Bitburner Plugin

1.7.9 verified Fri May 01 auth: no javascript

An ESBuild plugin (v1.7.9) that uses Bitburner's Remote API to push compiled build results directly into the game. It supports automatic file uploading, file mirroring for bidirectional sync, and distribution of scripts to multiple servers. Key differentiators: seamless integration with the Bitburner editor, support for React with ingame React/ReactDOM instances, and optional Netscript definitions generation. This plugin is actively maintained and requires Node >=20.0.0.

Common errors

error Error: Cannot find module 'esbuild-bitburner-plugin' ↓

cause Package not installed or wrong import path.

fix

Run 'npm install esbuild-bitburner-plugin' and ensure correct import syntax.

error TypeError: BitburnerPlugin is not a function ↓

cause Using default import correctly but module returns an object.

fix

Use named import: import { BitburnerPlugin } from 'esbuild-bitburner-plugin'.

error Error: listen EADDRINUSE :::12525 ↓

cause Port 12525 already in use by another instance.

fix

Kill the other process or specify a different port in the plugin options.

error Build failed with 1 error: error: Could not resolve 'React' ↓

cause React imports are expected to be resolved by the in-game React, but bundler tries to resolve locally.

fix

Mark React as external: external: ['React'] in esbuild config.

Warnings

gotcha Plugin only works with esbuild's context() API; using build() directly will not trigger uploads. ↓

fix Use context() with .watch() or .rebuild() instead of build().

breaking Node.js >=20.0.0 is required; older versions will cause runtime errors. ↓

fix Upgrade Node.js to version 20.0.0 or later.

gotcha File structure in outdir determines target server; e.g., build/home/foo.js uploads to home server. ↓

fix Ensure outdir contains subdirectories named after in-game servers.

deprecated The 'types' option may be renamed in future versions; check migration guides. ↓

fix Monitor GitHub releases for deprecations.

Install

npm install esbuild-bitburner-plugin

yarn add esbuild-bitburner-plugin

pnpm add esbuild-bitburner-plugin

Imports

BitburnerPlugin

wrong

const BitburnerPlugin = require('esbuild-bitburner-plugin')

correct

import { BitburnerPlugin } from 'esbuild-bitburner-plugin'

ESM-only; CommonJS require() will fail with the default export.

BitburnerPlugin

wrong

const BitburnerPlugin = require('esbuild-bitburner-plugin')

correct

const { BitburnerPlugin } = await import('esbuild-bitburner-plugin')

For dynamic imports, use ESM dynamic import.

BitburnerPlugin

wrong

import * as BitburnerPlugin from 'esbuild-bitburner-plugin'

correct

import BitburnerPlugin from 'esbuild-bitburner-plugin'

The default export is the plugin function; the named export is also available.

Quickstart

Sets up an ESBuild context with the Bitburner plugin to watch and auto-upload scripts to the game.

import { context } from 'esbuild';
import { BitburnerPlugin } from 'esbuild-bitburner-plugin';

const createContext = async () => {
  return await context({
    entryPoints: ['servers/**/*.js', 'servers/**/*.ts'],
    outbase: './servers',
    outdir: './build',
    plugins: [BitburnerPlugin({
      port: 12525,
      types: 'NetscriptDefinitions.d.ts',
    })],
    bundle: true,
    format: 'esm',
    platform: 'browser',
    logLevel: 'info',
  });
};

const ctx = await createContext();
ctx.watch();