bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/bundler/{macros.md → macros.mdx}

@@ -1,10 +1,13 @@
-Macros are a mechanism for running JavaScript functions _at bundle-time_. The value returned from these functions are directly inlined into your bundle.
+---
+title: Macros
+description: Run JavaScript functions at bundle-time with Bun macros
+---
 
-<!-- embed the result in your (browser) bundle. This is useful for things like embedding the current Git commit hash in your code, making fetch requests to your API at build-time, dead code elimination, and more. -->
+Macros are a mechanism for running JavaScript functions at bundle-time. The value returned from these functions are directly inlined into your bundle.
 
 As a toy example, consider this simple function that returns a random number.
 
-```ts
+```ts title="random.ts" icon="/icons/typescript.svg"
 export function random() {
   return Math.random();
 }
@@ -12,24 +15,28 @@ export function random() {
 
 This is just a regular function in a regular file, but we can use it as a macro like so:
 
-```ts#cli.tsx
-import { random } from './random.ts' with { type: 'macro' };
+```tsx title="cli.tsx" icon="/icons/typescript.svg"
+import { random } from "./random.ts" with { type: "macro" };
 
 console.log(`Your random number is ${random()}`);
 ```
 
-{% callout %}
-**Note** — Macros are indicated using [_import attribute_](https://github.com/tc39/proposal-import-attributes) syntax. If you haven't seen this syntax before, it's a Stage 3 TC39 proposal that lets you attach additional metadata to `import` statements.
-{% /callout %}
+<Note>
+  Macros are indicated using import attribute syntax. If you haven't seen this syntax before, it's a Stage 3 TC39
+  proposal that lets you attach additional metadata to import statements.
+</Note>
 
 Now we'll bundle this file with `bun build`. The bundled file will be printed to stdout.
 
-```bash
-$ bun build ./cli.tsx
+```bash terminal icon="terminal"
+bun build ./cli.tsx
+```
+
+```js
 console.log(`Your random number is ${0.6805550949689833}`);
 ```
 
-As you can see, the source code of the `random` function occurs nowhere in the bundle. Instead, it is executed _during bundling_ and function call (`random()`) is replaced with the result of the function. Since the source code will never be included in the bundle, macros can safely perform privileged operations like reading from a database.
+As you can see, the source code of the `random` function occurs nowhere in the bundle. Instead, it is executed during bundling and function call (`random()`) is replaced with the result of the function. Since the source code will never be included in the bundle, macros can safely perform privileged operations like reading from a database.
 
 ## When to use macros
 
@@ -41,8 +48,8 @@ If you find yourself running a lot of code at bundle-time though, consider runni
 
 Bun Macros are import statements annotated using either:
 
-- `with { type: 'macro' }` — an [import attribute](https://github.com/tc39/proposal-import-attributes), a Stage 3 ECMA Scrd
-- `assert { type: 'macro' }` — an import assertion, an earlier incarnation of import attributes that has now been abandoned (but is [already supported](https://caniuse.com/mdn-javascript_statements_import_import_assertions) by a number of browsers and runtimes)
+- `with { type: 'macro' }` — an import attribute, a Stage 3 ECMA Script proposal
+- `assert { type: 'macro' }` — an import assertion, an earlier incarnation of import attributes that has now been abandoned (but is already supported by a number of browsers and runtimes)
 
 ## Security considerations
 
@@ -50,7 +57,7 @@ Macros must explicitly be imported with `{ type: "macro" }` in order to be execu
 
 You can disable macros entirely by passing the `--no-macros` flag to Bun. It produces a build error like this:
 
-```js
+```
 error: Macros are disabled
 
 foo();
@@ -58,9 +65,9 @@ foo();
 ./hello.js:3:1 53
 ```
 
-To reduce the potential attack surface for malicious packages, macros cannot be _invoked_ from inside `node_modules/**/*`. If a package attempts to invoke a macro, you'll see an error like this:
+To reduce the potential attack surface for malicious packages, macros cannot be invoked from inside `node_modules/**/*`. If a package attempts to invoke a macro, you'll see an error like this:
 
-```js
+```
 error: For security reasons, macros cannot be run from node_modules.
 
 beEvil();
@@ -70,17 +77,17 @@ node_modules/evil/index.js:3:1 50
 
 Your application code can still import macros from `node_modules` and invoke them.
 
-```ts
+```ts title="cli.tsx" icon="/icons/typescript.svg"
 import { macro } from "some-package" with { type: "macro" };
 
 macro();
 ```
 
-## Export condition `"macro"`
+## Export condition "macro"
 
-When shipping a library containing a macro to `npm` or another package registry, use the `"macro"` [export condition](https://nodejs.org/api/packages.html#conditional-exports) to provide a special version of your package exclusively for the macro environment.
+When shipping a library containing a macro to npm or another package registry, use the `"macro"` export condition to provide a special version of your package exclusively for the macro environment.
 
-```jsonc#package.json
+```json title="package.json" icon="file-code"
 {
   "name": "my-package",
   "exports": {
@@ -94,7 +101,7 @@ When shipping a library containing a macro to `npm` or another package registry,
 
 With this configuration, users can consume your package at runtime or at bundle-time using the same import specifier:
 
-```ts
+```ts title="index.ts" icon="/icons/typescript.svg"
 import pkg from "my-package"; // runtime import
 import { macro } from "my-package" with { type: "macro" }; // macro import
 ```
@@ -105,15 +112,15 @@ The first import will resolve to `./node_modules/my-package/index.js`, while the
 
 When Bun's transpiler sees a macro import, it calls the function inside the transpiler using Bun's JavaScript runtime and converts the return value from JavaScript into an AST node. These JavaScript functions are called at bundle-time, not runtime.
 
-Macros are executed synchronously in the transpiler during the visiting phase—before plugins and before the transpiler generates the AST. They are executed in the order they are imported. The transpiler will wait for the macro to finish executing before continuing. The transpiler will also `await` any `Promise` returned by a macro.
+Macros are executed synchronously in the transpiler during the visiting phase—before plugins and before the transpiler generates the AST. They are executed in the order they are imported. The transpiler will wait for the macro to finish executing before continuing. The transpiler will also await any Promise returned by a macro.
 
 Bun's bundler is multi-threaded. As such, macros execute in parallel inside of multiple spawned JavaScript "workers".
 
 ## Dead code elimination
 
-The bundler performs dead code elimination _after_ running and inlining macros. So given the following macro:
+The bundler performs dead code elimination after running and inlining macros. So given the following macro:
 
-```ts#returnFalse.ts
+```ts title="returnFalse.ts" icon="/icons/typescript.svg"
 export function returnFalse() {
   return false;
 }
@@ -121,7 +128,7 @@ export function returnFalse() {
 
 ...then bundling the following file will produce an empty bundle, provided that the minify syntax option is enabled.
 
-```ts
+```ts title="index.ts" icon="/icons/typescript.svg"
 import { returnFalse } from "./returnFalse.ts" with { type: "macro" };
 
 if (returnFalse()) {
@@ -133,19 +140,19 @@ if (returnFalse()) {
 
 Bun's transpiler needs to be able to serialize the result of the macro so it can be inlined into the AST. All JSON-compatible data structures are supported:
 
-```ts#macro.ts
+```ts title="macro.ts" icon="/icons/typescript.svg"
 export function getObject() {
   return {
     foo: "bar",
     baz: 123,
-    array: [ 1, 2, { nested: "value" }],
+    array: [1, 2, { nested: "value" }],
   };
 }
 ```
 
-Macros can be async, or return `Promise` instances. Bun's transpiler will automatically `await` the `Promise` and inline the result.
+Macros can be async, or return Promise instances. Bun's transpiler will automatically await the Promise and inline the result.
 
-```ts#macro.ts
+```ts title="macro.ts" icon="/icons/typescript.svg"
 export async function getText() {
   return "async value";
 }
@@ -153,21 +160,21 @@ export async function getText() {
 
 The transpiler implements special logic for serializing common data formats like `Response`, `Blob`, `TypedArray`.
 
-- `TypedArray`: Resolves to a base64-encoded string.
-- `Response`: Bun will read the `Content-Type` and serialize accordingly; for instance, a `Response` with type `application/json` will be automatically parsed into an object and `text/plain` will be inlined as a string. Responses with an unrecognized or `undefined` `type` will be base-64 encoded.
-- `Blob`: As with `Response`, the serialization depends on the `type` property.
+- **TypedArray**: Resolves to a base64-encoded string.
+- **Response**: Bun will read the `Content-Type` and serialize accordingly; for instance, a Response with type `application/json` will be automatically parsed into an object and `text/plain` will be inlined as a string. Responses with an unrecognized or undefined type will be base-64 encoded.
+- **Blob**: As with Response, the serialization depends on the `type` property.
 
 The result of `fetch` is `Promise<Response>`, so it can be directly returned.
 
-```ts#macro.ts
+```ts title="macro.ts" icon="/icons/typescript.svg"
 export function getObject() {
-  return fetch("https://bun.com")
+  return fetch("https://bun.com");
 }
 ```
 
 Functions and instances of most classes (except those mentioned above) are not serializable.
 
-```ts
+```ts title="macro.ts" icon="/icons/typescript.svg"
 export function getText(url: string) {
   // this doesn't work!
   return () => {};
@@ -178,7 +185,7 @@ export function getText(url: string) {
 
 Macros can accept inputs, but only in limited cases. The value must be statically known. For example, the following is not allowed:
 
-```ts
+```ts title="index.ts" icon="/icons/typescript.svg"
 import { getText } from "./getText.ts" with { type: "macro" };
 
 export function howLong() {
@@ -192,7 +199,7 @@ export function howLong() {
 
 However, if the value of `foo` is known at bundle-time (say, if it's a constant or the result of another macro) then it's allowed:
 
-```ts
+```ts title="index.ts" icon="/icons/typescript.svg"
 import { getText } from "./getText.ts" with { type: "macro" };
 import { getFoo } from "./getFoo.ts" with { type: "macro" };
 
@@ -206,7 +213,7 @@ export function howLong() {
 
 This outputs:
 
-```ts
+```js
 function howLong() {
   console.log("The page is", 1322, "characters long");
 }
@@ -217,11 +224,9 @@ export { howLong };
 
 ### Embed latest git commit hash
 
-{% codetabs %}
-
-```ts#getGitCommitHash.ts
+```ts title="getGitCommitHash.ts" icon="/icons/typescript.svg"
 export function getGitCommitHash() {
-  const {stdout} = Bun.spawnSync({
+  const { stdout } = Bun.spawnSync({
     cmd: ["git", "rev-parse", "HEAD"],
     stdout: "pipe",
   });
@@ -230,33 +235,32 @@ export function getGitCommitHash() {
 }
 ```
 
-{% /codetabs %}
-
-<!-- --target=browser so they can clearly see it's for browsers -->
-
 When we build it, the `getGitCommitHash` is replaced with the result of calling the function:
 
-{% codetabs %}
+<CodeGroup>
 
-```ts#input
-import { getGitCommitHash } from './getGitCommitHash.ts' with { type: 'macro' };
+```ts input
+import { getGitCommitHash } from "./getGitCommitHash.ts" with { type: "macro" };
 
 console.log(`The current Git commit hash is ${getGitCommitHash()}`);
 ```
 
-```bash#output
-console.log(`The current Git commit hash is 3ee3259104f`);
+```ts output
+console.log(`The current Git commit hash is 3ee3259104e4507cf62c160f0ff5357ec4c7a7f8`);
 ```
 
-{% /codetabs %}
+</CodeGroup>
 
-You're probably thinking "Why not just use `process.env.GIT_COMMIT_HASH`?" Well, you can do that too. But can you do this with an environment variable?
+<Info>
+  You're probably thinking "Why not just use `process.env.GIT_COMMIT_HASH`?" Well, you can do that too. But can you do
+  this with an environment variable?
+</Info>
 
-### Make `fetch()` requests at bundle-time
+### Make fetch() requests at bundle-time
 
 In this example, we make an outgoing HTTP request using `fetch()`, parse the HTML response using `HTMLRewriter`, and return an object containing the title and meta tags–all at bundle-time.
 
-```ts
+```ts title="meta.ts" icon="/icons/typescript.svg"
 export async function extractMetaTags(url: string) {
   const response = await fetch(url);
   const meta = {
@@ -271,9 +275,7 @@ export async function extractMetaTags(url: string) {
     .on("meta", {
       element(element) {
         const name =
-          element.getAttribute("name") ||
-          element.getAttribute("property") ||
-          element.getAttribute("itemprop");
+          element.getAttribute("name") || element.getAttribute("property") || element.getAttribute("itemprop");
 
         if (name) meta[name] = element.getAttribute("content");
       },
@@ -284,14 +286,12 @@ export async function extractMetaTags(url: string) {
 }
 ```
 
-<!-- --target=browser so they can clearly see it's for browsers -->
-
-The `extractMetaTags` function is erased at bundle-time and replaced with the result of the function call. This means that the `fetch` request happens at bundle-time, and the result is embedded in the bundle. Also, the branch throwing the error is eliminated since it's unreachable.
+The `extractMetaTags` function is erased at bundle-time and replaced with the result of the function call. This means that the fetch request happens at bundle-time, and the result is embedded in the bundle. Also, the branch throwing the error is eliminated since it's unreachable.
 
-{% codetabs %}
+<CodeGroup>
 
-```ts#input
-import { extractMetaTags } from './meta.ts' with { type: 'macro' };
+```jsx input
+import { extractMetaTags } from "./meta.ts" with { type: "macro" };
 
 export const Head = () => {
   const headTags = extractMetaTags("https://example.com");
@@ -300,30 +300,29 @@ export const Head = () => {
     throw new Error("Expected title to be 'Example Domain'");
   }
 
-  return <head>
-    <title>{headTags.title}</title>
-    <meta name="viewport" content={headTags.viewport} />
-  </head>;
+  return (
+    <head>
+      <title>{headTags.title}</title>
+      <meta name="viewport" content={headTags.viewport} />
+    </head>
+  );
 };
 ```
 
-```ts#output
-import { jsx, jsxs } from "react/jsx-runtime";
+```jsx output
 export const Head = () => {
-  jsxs("head", {
-    children: [
-      jsx("title", {
-        children: "Example Domain",
-      }),
-      jsx("meta", {
-        name: "viewport",
-        content: "width=device-width, initial-scale=1",
-      }),
-    ],
-  });
-};
+  const headTags = {
+    title: "Example Domain",
+    viewport: "width=device-width, initial-scale=1",
+  };
 
-export { Head };
+  return (
+    <head>
+      <title>{headTags.title}</title>
+      <meta name="viewport" content={headTags.viewport} />
+    </head>
+  );
+};
 ```
 
-{% /codetabs %}
+</CodeGroup>