Macros - Bun

Macros are JavaScript functions that run at bundle-time. Their return values are inlined directly into your bundle. As a toy example, consider this function that returns a random number.

random.ts

export function random() {
  return Math.random();
}

This is a regular function in a regular file, but you can use it as a macro:

cli.tsx

import { random } from "./random.ts" with { type: "macro" };

console.log(`Your random number is ${random()}`);

Macros are marked with import attribute syntax, a Stage 3 TC39 proposal for attaching additional metadata to import statements.

Bundle the file with bun build. The bundled file is printed to stdout.

terminal

bun build ./cli.tsx

console.log(`Your random number is ${0.6805550949689833}`);

The source code of the random function occurs nowhere in the bundle. Instead, it runs during bundling and the call (random()) is replaced with its result. Since the source code is never included in the bundle, macros can safely perform privileged operations like reading from a database.

When to use macros

For small things you would otherwise write a one-off build script for, bundle-time code execution can be easier to maintain. It lives with the rest of your code, it runs with the rest of the build, it is automatically parallelized, and if it fails, the build fails too. If you find yourself running a lot of code at bundle-time though, consider running a server instead.

Import attributes

Macros are import statements annotated with either:

with { type: 'macro' } — an import attribute, a Stage 3 ECMAScript 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

Macros must be explicitly imported with { type: "macro" } to run at bundle-time. These imports have no effect if they are not called, unlike regular JavaScript imports which may have side effects. You can disable macros entirely with the --no-macros flag. It produces a build error like this:

error: Macros are disabled

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:

error: For security reasons, macros cannot be run from node_modules.

beEvil();
^
node_modules/evil/index.js:3:1 50

Your application code can still import macros from node_modules and invoke them.

cli.tsx

import { macro } from "some-package" with { type: "macro" };

macro();

Export condition “macro”

When shipping a library containing a macro to npm or another package registry, use the "macro" export condition to provide a version of your package exclusively for the macro environment.

package.json

{
  "name": "my-package",
  "exports": {
    "import": "./index.js",
    "require": "./index.js",
    "default": "./index.js",
    "macro": "./index.macro.js"
  }
}

With this configuration, users can consume your package at runtime or at bundle-time using the same import specifier:

index.ts

import pkg from "my-package"; // runtime import
import { macro } from "my-package" with { type: "macro" }; // macro import

The first import resolves to ./node_modules/my-package/index.js; Bun’s bundler resolves the second to ./node_modules/my-package/index.macro.js.

Execution

When Bun’s transpiler sees a macro import, it calls the function using Bun’s JavaScript runtime and converts the return value into an AST node. Macros run synchronously in the transpiler during the visiting phase, before plugins and before the transpiler generates the AST. They run in the order they are imported. The transpiler waits for each macro to finish before continuing, and awaits any Promise a macro returns. Bun’s bundler is multi-threaded, so macros execute in parallel in multiple spawned JavaScript “workers”.

Dead code elimination

The bundler performs dead code elimination after running and inlining macros. Given the following macro:

returnFalse.ts

export function returnFalse() {
  return false;
}

…bundling the following file produces an empty bundle, provided that the minify syntax option is enabled.

index.ts

import { returnFalse } from "./returnFalse.ts" with { type: "macro" };

if (returnFalse()) {
  console.log("This code is eliminated");
}

Serializability

Bun’s transpiler must be able to serialize the result of the macro to inline it into the AST. All JSON-compatible data structures are supported:

macro.ts

export function getObject() {
  return {
    foo: "bar",
    baz: 123,
    array: [1, 2, { nested: "value" }],
  };
}

Macros can be async, or return Promise instances. Bun’s transpiler awaits the Promise and inlines the result.

macro.ts

export async function getText() {
  return "async value";
}

The transpiler implements special logic for serializing common data formats like Response and Blob.

Response: Bun reads the Content-Type and serializes accordingly; for example, a Response with type application/json is parsed into an object and text/plain is inlined as a string. Responses with an unrecognized or undefined type are base64-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.

macro.ts

export function getObject() {
  return fetch("https://bun.com");
}

Functions and instances of most classes (except those listed earlier) are not serializable.

macro.ts

export function getText(url: string) {
  // this doesn't work!
  return () => {};
}

Arguments

Macros can accept inputs, but only in limited cases. The value must be statically known. For example, the following is not allowed:

index.ts

import { getText } from "./getText.ts" with { type: "macro" };

export function howLong() {
  // the value of `foo` cannot be statically known
  const foo = Math.random() ? "foo" : "bar";

  const text = getText(`https://example.com/${foo}`);
  console.log("The page is ", text.length, " characters long");
}

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:

index.ts

import { getText } from "./getText.ts" with { type: "macro" };
import { getFoo } from "./getFoo.ts" with { type: "macro" };

export function howLong() {
  // this works because getFoo() is statically known
  const foo = getFoo();
  const text = getText(`https://example.com/${foo}`);
  console.log("The page is", text.length, "characters long");
}

This outputs:

function howLong() {
  console.log("The page is", 1322, "characters long");
}
export { howLong };

Examples

Embed latest git commit hash

getGitCommitHash.ts

export function getGitCommitHash() {
  const { stdout } = Bun.spawnSync({
    cmd: ["git", "rev-parse", "HEAD"],
    stdout: "pipe",
  });

  return stdout.toString();
}

When you build it, the getGitCommitHash call is replaced with the result of calling the function:

import { getGitCommitHash } from "./getGitCommitHash.ts" with { type: "macro" };

console.log(`The current Git commit hash is ${getGitCommitHash()}`);

console.log(`The current Git commit hash is 3ee3259104e4507cf62c160f0ff5357ec4c7a7f8`);

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?

Make fetch() requests at bundle-time

This example makes an outgoing HTTP request with fetch(), parses the HTML response with HTMLRewriter, and returns an object containing the title and meta tags, all at bundle-time.

meta.ts

export async function extractMetaTags(url: string) {
  const response = await fetch(url);
  const meta = {
    title: "",
  };
  new HTMLRewriter()
    .on("title", {
      text(element) {
        meta.title += element.text;
      },
    })
    .on("meta", {
      element(element) {
        const name =
          element.getAttribute("name") || element.getAttribute("property") || element.getAttribute("itemprop");

        if (name) meta[name] = element.getAttribute("content");
      },
    })
    .transform(response);

  return meta;
}

The extractMetaTags function is erased at bundle-time and replaced with the result of the function call: the fetch request happens at bundle-time, and the result is embedded in the bundle. The branch throwing the error is also eliminated since it’s unreachable.

import { extractMetaTags } from "./meta.ts" with { type: "macro" };

export const Head = () => {
  const headTags = extractMetaTags("https://example.com");

  if (headTags.title !== "Example Domain") {
    throw new Error("Expected title to be 'Example Domain'");
  }

  return (
    <head>
      <title>{headTags.title}</title>
      <meta name="viewport" content={headTags.viewport} />
    </head>
  );
};

export const Head = () => {
  const headTags = {
    title: "Example Domain",
    viewport: "width=device-width, initial-scale=1",
  };

  return (
    <head>
      <title>{headTags.title}</title>
      <meta name="viewport" content={headTags.viewport} />
    </head>
  );
};

​When to use macros

​Import attributes

​Security considerations

​Export condition “macro”

​Execution

​Dead code elimination

​Serializability

​Arguments

​Examples

​Embed latest git commit hash

​Make fetch() requests at bundle-time

When to use macros

Import attributes

Security considerations

Export condition “macro”

Execution

Dead code elimination

Serializability

Arguments

Examples

Embed latest git commit hash

Make fetch() requests at bundle-time