aboutsummaryrefslogtreecommitdiff
path: root/docs/bundler/plugins.md
diff options
context:
space:
mode:
authorGravatar Colin McDonnell <colinmcd94@gmail.com> 2023-04-26 20:07:30 -0700
committerGravatar GitHub <noreply@github.com> 2023-04-26 20:07:30 -0700
commit8ba13f273c2fb4cd18e144f885a0c6b4b94e5880 (patch)
treecf9d42de2b840c0dcbfd578843507d2db1e36b8d /docs/bundler/plugins.md
parent68ab71eb13687ebb0889d085bb9c76132e452f60 (diff)
downloadbun-8ba13f273c2fb4cd18e144f885a0c6b4b94e5880.tar.gz
bun-8ba13f273c2fb4cd18e144f885a0c6b4b94e5880.tar.zst
bun-8ba13f273c2fb4cd18e144f885a0c6b4b94e5880.zip
Add bundler documentation (#2753)
* WIP * WIP * WIP * Document API * Updates * Polish bundler docs * Tweaks * Tweak
Diffstat (limited to '')
-rw-r--r--docs/bundler/plugins.md (renamed from docs/runtime/plugins.md)42
1 files changed, 38 insertions, 4 deletions
diff --git a/docs/runtime/plugins.md b/docs/bundler/plugins.md
index 788bfb3ef..68d2b3107 100644
--- a/docs/runtime/plugins.md
+++ b/docs/bundler/plugins.md
@@ -2,29 +2,54 @@
**Note** — Introduced in Bun v0.1.11.
{% /callout %}
-Bun's runtime can be extended to support additional file types using _plugins_. Plugins can intercept imports and perform custom loading logic: reading files, transpiling code, etc. They can be used to extend Bun's runtime with _loaders_ for additional file types.
+Bun provides a universal plugin API that can be used to extend both the _runtime_ and _bundler_.
+
+Plugins intercept imports and perform custom loading logic: reading files, transpiling code, etc. They can be used to add support for additional file types, like `.scss` or `.yaml`. In the context of Bun's bundler, plugins can be used to implement framework-level features like CSS extraction, macros, and client-server code co-location.
## Usage
A plugin is defined as simple JavaScript object containing a `name` property and a `setup` function. Register a plugin with Bun using the `plugin` function.
```tsx#yamlPlugin.ts
-import { plugin } from "bun";
+import type { BunPlugin } from "bun";
-plugin({
+const myPlugin: BunPlugin = {
name: "YAML loader",
setup(build) {
// implementation
},
+};
+```
+
+This plugin can be passed into the `plugins` array when calling `Bun.build`.
+
+```ts
+Bun.build({
+ entrypoints: ["./app.ts"],
+ outdir: "./out",
+ plugins: [myPlugin],
});
```
+It can also be "registered" with the Bun runtime using the `Bun.plugin()` function. Once registered, the currently executing `bun` process will incorporate the plugin into its module resolution algorithm.
+
+```ts
+Bun.plugin(myPlugin);
+```
+
To consume this plugin, add this file to the `preload` option in your [`bunfig.toml`](/docs/runtime/configuration). Bun automatically loads the files/modules specified in `preload` before running a file.
```toml
preload = ["./yamlPlugin.ts"]
```
+To preload files during `bun test`:
+
+```toml
+[test]
+preload = ["./loader.ts"]
+```
+
{% details summary="Usage without preload" %}
Alternatively, you can import this file manually at the top of your project's entrypoint, before any application code is imported.
@@ -243,15 +268,24 @@ namespace Bun {
}
type PluginBuilder = {
+ onResolve: (
+ args: { filter: RegExp; namespace?: string },
+ callback: (args: { path: string; importer: string }) => {
+ path: string;
+ namespace?: string;
+ } | void,
+ ) => void;
onLoad: (
args: { filter: RegExp; namespace?: string },
callback: (args: { path: string }) => {
- loader?: "js" | "jsx" | "ts" | "tsx" | "json" | "toml" | "object";
+ loader?: Loader;
contents?: string;
exports?: Record<string, any>;
},
) => void;
};
+
+type Loader = "js" | "jsx" | "ts" | "tsx" | "json" | "toml" | "object";
```
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`.