method

BunPlugin.setup

build: PluginBuilder
): void | Promise<void>;

Called when the plugin is loaded.

This function may be called in the same tick that it is registered, or it may be called later. It may be called multiple times for different targets.

@param build

The builder object for registering plugin hooks

Referenced types

interface PluginBuilder

The builder object passed to Bun.plugin

  • config: BuildConfig & { plugins: BunPlugin[] }

    The config object passed to Bun.build as is. Can be mutated.

  • specifier: string,
    callback: () => OnLoadResult | Promise<OnLoadResult>
    ): this;

    Create a lazy-loaded virtual module that can be imported or required from other modules

    @param specifier

    The module specifier to register the callback for

    @param callback

    The function to run when the module is imported or required

    @returns

    this for method chaining

    Bun.plugin({
  setup(builder) {
    builder.module("hello:world", () => {
      return { exports: { foo: "bar" }, loader: "object" };
    });
  },
});

// sometime later
const { foo } = await import("hello:world");
console.log(foo); // "bar"

// or
const { foo } = require("hello:world");
console.log(foo); // "bar"
  • callback: OnEndCallback
    ): this;

    Register a callback that runs when bundling ends, after all modules have been bundled and the build is complete.

    @returns

    this for method chaining

    const plugin: Bun.BunPlugin = {
  name: "my-plugin",
  setup(builder) {
    builder.onEnd((result) => {
      console.log("bundle just finished!!", result);
    });
  },
};
  • constraints: PluginConstraints,
    callback: OnLoadCallback
    ): this;

    Register a callback to load imports with a specific import specifier

    @param constraints

    The constraints to apply the plugin to

    @param callback

    The callback to handle the import

    @returns

    this for method chaining

    Bun.plugin({
  setup(builder) {
    builder.onLoad({ filter: /^hello:world$/ }, (args) => {
      return { exports: { foo: "bar" }, loader: "object" };
    });
  },
});
  • constraints: PluginConstraints,
    callback: OnResolveCallback
    ): this;

    Register a callback to resolve imports matching a filter and/or namespace

    @param constraints

    The constraints to apply the plugin to

    @param callback

    The callback to handle the import

    @returns

    this for method chaining

    Bun.plugin({
  setup(builder) {
    builder.onResolve({ filter: /^wat$/ }, (args) => {
      return { path: "/tmp/woah.js" };
    });
  },
});
  • callback: OnStartCallback
    ): this;

    Register a callback that runs when bundling starts. With hot module reloading, it runs at the start of each incremental rebuild.

    @returns

    this for method chaining

    Bun.plugin({
  setup(builder) {
    builder.onStart(() => {
      console.log("bundle just started!!")
    });
  },
});