diff options
author | 2023-04-26 20:07:30 -0700 | |
---|---|---|
committer | 2023-04-26 20:07:30 -0700 | |
commit | 8ba13f273c2fb4cd18e144f885a0c6b4b94e5880 (patch) | |
tree | cf9d42de2b840c0dcbfd578843507d2db1e36b8d /docs/bundler/plugins.md | |
parent | 68ab71eb13687ebb0889d085bb9c76132e452f60 (diff) | |
download | bun-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`. |