.defer(), .onStart(), and some small CSS changes (#15041)

Author: zackradisic

docs/runtime/plugins.md

@@ -302,7 +302,7 @@ require("my-object-virtual-module"); // { baz: "quix" }
 await import("my-object-virtual-module"); // { baz: "quix" }
 ```
 
-## Reading the config
+## Reading or modifying the config
 
 Plugins can read and write to the [build config](https://bun.sh/docs/bundler#api) with `build.config`.
 
@@ -327,7 +327,43 @@ Bun.build({
 });
 ```
 
-## Reference
+{% callout %}
+
+**NOTE**: Plugin lifcycle callbacks (`onStart()`, `onResolve()`, etc.) do not have the ability to modify the `build.config` object in the `setup()` function. If you want to mutate `build.config`, you must do so directly in the `setup()` function:
+
+```ts
+Bun.build({
+  entrypoints: ["./app.ts"],
+  outdir: "./dist",
+  sourcemap: "external",
+  plugins: [
+    {
+      name: "demo",
+      setup(build) {
+        // ✅ good! modifying it directly in the setup() function
+        build.config.minify = true;
+
+        build.onStart(() => {
+          // 🚫 uh-oh! this won't work!
+          build.config.minify = false;
+        });
+      },
+    },
+  ],
+});
+```
+
+{% /callout %}
+
+## Lifecycle callbacks
+
+Plugins can register callbacks to be run at various points in the lifecycle of a bundle:
+
+- [`onStart()`](#onstart): Run once the bundler has started a bundle
+- [`onResolve()`](#onresolve): Run before a module is resolved
+- [`onLoad()`](#onload): Run before a module is loaded.
+
+A rough overview of the types (please refer to Bun's `bun.d.ts` for the full type definitions):
 
 ```ts
 namespace Bun {
@@ -338,6 +374,7 @@ namespace Bun {
 }
 
 type PluginBuilder = {
+  onStart(callback: () => void): void;
   onResolve: (
     args: { filter: RegExp; namespace?: string },
     callback: (args: { path: string; importer: string }) => {
@@ -356,7 +393,213 @@ type PluginBuilder = {
   config: BuildConfig;
 };
 
-type Loader = "js" | "jsx" | "ts" | "tsx" | "json" | "toml" | "object";
+type Loader = "js" | "jsx" | "ts" | "tsx" | "css" | "json" | "toml" | "object";
+```
+
+### Namespaces
+
+`onLoad` and `onResolve` accept an optional `namespace` string. What is a namespaace?
+
+Every module has a namespace. Namespaces are used to prefix the import in transpiled code; for instance, a loader with a `filter: /\.yaml$/` and `namespace: "yaml:"` will transform an import from `./myfile.yaml` into `yaml:./myfile.yaml`.
+
+The default namespace is `"file"` and it is not necessary to specify it, for instance: `import myModule frmo "./my-module.ts"` is the same as `import myModule from "file:./my-module.ts"`.
+
+Other common namespaces are:
+
+- `"bun"`: for Bun-specific modules (e.g. `"bun:test"`, `"bun:sqlite"`)
+- `"node"`: for Node.js modules (e.g. `"node:fs"`, `"node:path"`)
+
+### `onStart`
+
+```ts
+onStart(callback: () => void): Promise<void> | void;
+```
+
+Registers a callback to be run when the bundler starts a new bundle.
+
+```ts
+import { plugin } from "bun";
+
+plugin({
+  name: "onStart example",
+
+  setup(build) {
+    build.onStart(() => {
+      console.log("Bundle started!");
+    });
+  },
+});
+```
+
+The callback can return a `Promise`. After the bundle process has initialized, the bundler waits until all `onStart()` callbacks have completed before continuing.
+
+For example:
+
+```ts
+const result = await Bun.build({
+  entrypoints: ["./app.ts"],
+  outdir: "./dist",
+  sourcemap: "external",
+  plugins: [
+    {
+      name: "Sleep for 10 seconds",
+      setup(build) {
+        build.onStart(async () => {
+          await Bunlog.sleep(10_000);
+        });
+      },
+    },
+    {
+      name: "Log bundle time to a file",
+      setup(build) {
+        build.onStart(async () => {
+          const now = Date.now();
+          await Bun.$`echo ${now} > bundle-time.txt`;
+        });
+      },
+    },
+  ],
+});
+```
+
+In the above example, Bun will wait until the first `onStart()` (sleeping for 10 seconds) has completed, _as well as_ the second `onStart()` (writing the bundle time to a file).
+
+Note that `onStart()` callbacks (like every other lifecycle callback) do not have the ability to modify the `build.config` object. If you want to mutate `build.config`, you must do so directly in the `setup()` function.
+
+### `onResolve`
+
+```ts
+onResolve(
+  args: { filter: RegExp; namespace?: string },
+  callback: (args: { path: string; importer: string }) => {
+    path: string;
+    namespace?: string;
+  } | void,
+): void;
+```
+
+To bundle your project, Bun walks down the dependency tree of all modules in your project. For each imported module, Bun actually has to find and read that module. The "finding" part is known as "resolving" a module.
+
+The `onResolve()` plugin lifecycle callback allows you to configure how a module is resolved.
+
+The first argument to `onResolve()` is an object with a `filter` and [`namespace`](#what-is-a-namespace) property. The filter is a regular expression which is run on the import string. Effectively, these allow you to filter which modules your custom resolution logic will apply to.
+
+The second argument to `onResolve()` is a callback which is run for each module import Bun finds that matches the `filter` and `namespace` defined in the first argument.
+
+The callback receives as input the _path_ to the matching module. The callback can return a _new path_ for the module. Bun will read the contents of the _new path_ and parse it as a module.
+
+For example, redirecting all imports to `images/` to `./public/images/`:
+
+```ts
+import { plugin } from "bun";
+
+plugin({
+  name: "onResolve example",
+  setup(build) {
+    build.onResolve({ filter: /.*/, namespace: "file" }, args => {
+      if (args.path.startsWith("images/")) {
+        return {
+          path: args.path.replace("images/", "./public/images/"),
+        };
+      }
+    });
+  },
+});
+```
+
+### `onLoad`
+
+```ts
+onLoad(
+  args: { filter: RegExp; namespace?: string },
+  callback: (args: { path: string, importer: string, namespace: string, kind: ImportKind  }) => {
+    loader?: Loader;
+    contents?: string;
+    exports?: Record<string, any>;
+  },
+): void;
+```
+
+After Bun's bundler has resolved a module, it needs to read the contents of the module and parse it.
+
+The `onLoad()` plugin lifecycle callback allows you to modify the _contents_ of a module before it is read and parsed by Bun.
+
+Like `onResolve()`, the first argument to `onLoad()` allows you to filter which modules this invocation of `onLoad()` will apply to.
+
+The second argument to `onLoad()` is a callback which is run for each matching module _before_ Bun loads the contents of the module into memory.
+
+This callback receives as input the _path_ to the matching module, the _importer_ of the module (the module that imported the module), the _namespace_ of the module, and the _kind_ of the module.
+
+The callback can return a new `contents` string for the module as well as a new `loader`.
+
+For example:
+
+```ts
+import { plugin } from "bun";
+
+plugin({
+  name: "env plugin",
+  setup(build) {
+    build.onLoad({ filter: /env/, namespace: "file" }, args => {
+      return {
+        contents: `export default ${JSON.stringify(process.env)}`,
+        loader: "js",
+      };
+    });
+  },
+});
+```
+
+This plugin will transform all imports of the form `import env from "env"` into a JavaScript module that exports the current environment variables.
+
+#### `.defer()`
+
+One of the arguments passed to the `onLoad` callback is a `defer` function. This function returns a `Promise` that is resolved when all _other_ modules have been loaded.
+
+This allows you to delay execution of the `onLoad` callback until all other modules have been loaded.
+
+This is useful for returning contens of a module that depends on other modules.
+
+##### Example: tracking and reporting unused exports
+
+```ts
+import { plugin } from "bun";
+
+plugin({
+  name: "track imports",
+  setup(build) {
+    const transpiler = new Bun.Transpiler();
+
+    let trackedImports: Record<string, number> = {};
+
+    // Each module that goes through this onLoad callback
+    // will record its imports in `trackedImports`
+    build.onLoad({ filter: /\.ts/ }, async ({ path }) => {
+      const contents = await Bun.file(path).arrayBuffer();
+
+      const imports = transpiler.scanImports(contents);
+
+      for (const i of imports) {
+        trackedImports[i.path] = (trackedImports[i.path] || 0) + 1;
+      }
+
+      return undefined;
+    });
+
+    build.onLoad({ filter: /stats\.json/ }, async ({ defer }) => {
+      // Wait for all files to be loaded, ensuring
+      // that every file goes through the above `onLoad()` function
+      // and their imports tracked
+      await defer();
+
+      // Emit JSON containing the stats of each import
+      return {
+        contents: `export default ${JSON.stringify(trackedImports)}`,
+        loader: "json",
+      };
+    });
+  },
+});
 ```
 
-The `onLoad` method optionally accepts a `namespace` in addition to the `filter` regex. This namespace will be be used to prefix the import in transpiled code; for instance, a loader with a `filter: /\.yaml$/` and `namespace: "yaml:"` will transform an import from `./myfile.yaml` into `yaml:./myfile.yaml`.
+Note that the `.defer()` function currently has the limitation that it can only be called once per `onLoad` callback.

packages/bun-types/bun.d.ts

@@ -3785,7 +3785,7 @@ declare module "bun" {
     | "browser";
 
   /** https://bun.sh/docs/bundler/loaders */
-  type Loader = "js" | "jsx" | "ts" | "tsx" | "json" | "toml" | "file" | "napi" | "wasm" | "text";
+  type Loader = "js" | "jsx" | "ts" | "tsx" | "json" | "toml" | "file" | "napi" | "wasm" | "text" | "css";
 
   interface PluginConstraints {
     /**
@@ -3873,10 +3873,18 @@ declare module "bun" {
      * The default loader for this file extension
      */
     loader: Loader;
+
+    /**
+     * Defer the execution of this callback until all other modules have been parsed.
+     *
+     * @returns Promise which will be resolved when all modules have been parsed
+     */
+    defer: () => Promise<void>;
   }
 
   type OnLoadResult = OnLoadResultSourceCode | OnLoadResultObject | undefined;
   type OnLoadCallback = (args: OnLoadArgs) => OnLoadResult | Promise<OnLoadResult>;
+  type OnStartCallback = () => void | Promise<void>;
 
   interface OnResolveArgs {
     /**
@@ -3953,6 +3961,20 @@ declare module "bun" {
      * ```
      */
     onResolve(constraints: PluginConstraints, callback: OnResolveCallback): void;
+    /**
+     * Register a callback which will be invoked when bundling starts.
+     * @example
+     * ```ts
+     * Bun.plugin({
+     *   setup(builder) {
+     *     builder.onStart(() => {
+     *       console.log("bundle just started!!")
+     *     });
+     *   },
+     * });
+     * ```
+     */
+    onStart(callback: OnStartCallback): void;
     /**
      * The config object passed to `Bun.build` as is. Can be mutated.
      */