Das --define-Flag ermöglicht es Ihnen, statisch analysierbare Konstanten und Globals zu deklarieren. Es ersetzt alle Verwendungen eines Bezeichners oder einer Property in einer JavaScript- oder TypeScript-Datei durch einen konstanten Wert. Diese Funktion wird zur Laufzeit und auch in bun build unterstützt. Dies ist ähnlich wie #define in C/C++, aber für JavaScript.

bun --define process.env.NODE_ENV="'production'" src/index.ts # Runtime
bun build --define process.env.NODE_ENV="'production'" src/index.ts # Build

---

Diese statisch bekannten Werte werden von Bun für die Dead-Code-Eliminierung und andere Optimierungen verwendet.

if (process.env.NODE_ENV === "production") {
  console.log("Production mode");
} else {
  console.log("Development mode");
}

---

Bevor der Code die JavaScript-Engine erreicht, ersetzt Bun process.env.NODE_ENV durch "production".

if ("production" === "production") { 
  console.log("Production mode");
} else {
  console.log("Development mode");
}

---

Es hört hier nicht auf. Buns optimierender Transpiler ist schlau genug, um ein grundlegendes Constant Folding durchzuführen.

Da "production" === "production" immer true ist, ersetzt Bun den gesamten Ausdruck durch den true-Wert.

if (true) { 
  console.log("Production mode");
} else {
  console.log("Development mode");
}

---

Und schließlich erkennt Bun, dass der else-Zweig nicht erreichbar ist, und eliminiert ihn.

console.log("Production mode");

---

Welche Arten von Werten werden unterstützt?

Werte können Strings, Bezeichner, Properties oder JSON sein.

Globale Bezeichner ersetzen

Um alle Verwendungen von window zu undefined zu machen, können Sie den folgenden Befehl verwenden.

bun --define window="undefined" src/index.ts

Dies kann nützlich sein beim Server-Side Rendering (SSR) oder wenn Sie sicherstellen möchten, dass der Code nicht vom window-Objekt abhängt.

if (typeof window !== "undefined") {
  console.log("Client-side code");
} else {
  console.log("Server-side code");
}

Sie können den Wert auch auf einen anderen Bezeichner setzen. Um beispielsweise alle Verwendungen von global zu globalThis zu machen, können Sie den folgenden Befehl verwenden.

bun --define global="globalThis" src/index.ts

global ist ein globales Objekt in Node.js, aber nicht in Webbrowsern. Sie können dies verwenden, um einige Fälle zu beheben, in denen der Code annimmt, dass global verfügbar ist.

Werte durch JSON ersetzen

--define kann auch verwendet werden, um Werte durch JSON-Objekte und Arrays zu ersetzen.

Um alle Verwendungen von AWS durch das JSON-Objekt {"ACCESS_KEY":"abc","SECRET_KEY":"def"} zu ersetzen, können Sie den folgenden Befehl verwenden.

# JSON
bun --define AWS='{"ACCESS_KEY":"abc","SECRET_KEY":"def"}' src/index.ts

Diese werden in den entsprechenden JavaScript-Code transformiert.

Von:

console.log(AWS.ACCESS_KEY); // => "abc"

Zu:

console.log("abc");

Werte durch andere Properties ersetzen

Sie können auch Properties an das --define-Flag übergeben.

Um beispielsweise alle Verwendungen von console.write durch console.log zu ersetzen, können Sie den folgenden Befehl verwenden:

bun --define console.write=console.log src/index.ts

Das transformiert die folgende Eingabe:

console.write("Hello, world!");

In die folgende Ausgabe:

console.log("Hello, world!");

Wie unterscheidet sich dies vom Setzen einer Variable?

Sie können process.env.NODE_ENV auch in Ihrem Code auf "production" setzen, aber das hilft nicht bei der Dead-Code-Eliminierung. In JavaScript können Property-Zugriffe Nebenwirkungen haben. Getter und Setter können Funktionen sein und sogar dynamisch definiert werden (aufgrund von Prototyp-Ketten und Proxy). Selbst wenn Sie process.env.NODE_ENV auf "production" setzen, ist es in der nächsten Zeile für statische Analyse-Tools nicht sicher anzunehmen, dass process.env.NODE_ENV "production" ist.

Wie unterscheidet sich dies von Suchen-und-Ersetzen oder String-Ersetzung?

Das --define-Flag arbeitet auf AST-Ebene (Abstract Syntax Tree), nicht auf Textebene. Es geschieht während des Transpilierungsprozesses, was bedeutet, dass es für Optimierungen wie Dead-Code-Eliminierung verwendet werden kann.

String-Ersetzungstools haben tendenziell Probleme mit Escaping und ersetzen unbeabsichtigte Teile des Codes.