L'option --define peut être utilisée avec bun build et bun build --compile pour injecter des constantes au moment de la compilation dans votre application. Ceci est particulièrement utile pour intégrer des métadonnées comme les versions de compilation, les horodatages ou les indicateurs de configuration directement dans vos exécutables compilés.

bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/index.ts --outfile myapp

---

Pourquoi utiliser les constantes au moment de la compilation ?

Les constantes au moment de la compilation sont intégrées directement dans votre code compilé, ce qui les rend :

• Zéro surcharge d'exécution - Aucune recherche de variable d'environnement ou lecture de fichier
• Immuables - Les valeurs sont intégrées dans le binaire au moment de la compilation
• Optimisables - L'élimination du code mort peut supprimer les branches inutilisées
• Sécurisées - Aucune dépendance externe ou fichier de configuration à gérer

Ceci est similaire à gcc -D ou #define en C/C++, mais pour JavaScript/TypeScript.

---

Utilisation de base

Avec bun build

# Bundle avec constantes au moment de la compilation
bun build --define BUILD_VERSION='"1.0.0"' --define NODE_ENV='"production"' src/index.ts --outdir ./dist

Avec bun build --compile

# Compiler en exécutable avec constantes au moment de la compilation
bun build --compile --define BUILD_VERSION='"1.0.0"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/cli.ts --outfile mycli

API JavaScript

await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  define: {
    BUILD_VERSION: '"1.0.0"',
    BUILD_TIME: '"2024-01-15T10:30:00Z"',
    DEBUG: "false",
  },
});

---

Cas d'utilisation courants

Informations de version

Intégrez les métadonnées de version et de compilation directement dans votre exécutable :

// Ces constantes sont remplacées au moment de la compilation
declare const BUILD_VERSION: string;
declare const BUILD_TIME: string;
declare const GIT_COMMIT: string;

export function getVersion() {
  return {
    version: BUILD_VERSION,
    buildTime: BUILD_TIME,
    commit: GIT_COMMIT,
  };
}

bun build --compile \
  --define BUILD_VERSION='"1.2.3"' \
  --define BUILD_TIME='"2024-01-15T10:30:00Z"' \
  --define GIT_COMMIT='"abc123"' \
  src/cli.ts --outfile mycli

Indicateurs de fonctionnalité

Utilisez les constantes au moment de la compilation pour activer/désactiver des fonctionnalités :

// Remplacé au moment de la compilation
declare const ENABLE_ANALYTICS: boolean;
declare const ENABLE_DEBUG: boolean;

function trackEvent(event: string) {
  if (ENABLE_ANALYTICS) {
    // Ce bloc entier est supprimé si ENABLE_ANALYTICS est false
    console.log("Suivi :", event);
  }
}

if (ENABLE_DEBUG) {
  console.log("Mode débogage activé");
}

# Compilation production - analytique activé, débogage désactivé
bun build --compile --define ENABLE_ANALYTICS=true --define ENABLE_DEBUG=false src/app.ts --outfile app-prod

# Compilation développement - les deux activés
bun build --compile --define ENABLE_ANALYTICS=false --define ENABLE_DEBUG=true src/app.ts --outfile app-dev

Configuration

Remplacez les objets de configuration au moment de la compilation :

declare const CONFIG: {
  apiUrl: string;
  timeout: number;
  retries: number;
};

// CONFIG est remplacé par l'objet réel au moment de la compilation
const response = await fetch(CONFIG.apiUrl, {
  timeout: CONFIG.timeout,
});

bun build --compile --define 'CONFIG={"apiUrl":"https://api.example.com","timeout":5000,"retries":3}' src/app.ts --outfile app

---

Motifs avancés

Compilations spécifiques à l'environnement

Créez différents exécutables pour différents environnements :

{
  "scripts": {
    "build:dev": "bun build --compile --define NODE_ENV='\"development\"' --define API_URL='\"http://localhost:3000\"' src/app.ts --outfile app-dev",
    "build:staging": "bun build --compile --define NODE_ENV='\"staging\"' --define API_URL='\"https://staging.example.com\"' src/app.ts --outfile app-staging",
    "build:prod": "bun build --compile --define NODE_ENV='\"production\"' --define API_URL='\"https://api.example.com\"' src/app.ts --outfile app-prod"
  }
}

Utilisation de commandes shell pour des valeurs dynamiques

Générez des constantes au moment de la compilation à partir de commandes shell :

# Utiliser git pour obtenir le commit actuel et l'horodatage
bun build --compile \
  --define BUILD_VERSION="\"$(git describe --tags --always)\"" \
  --define BUILD_TIME="\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"" \
  --define GIT_COMMIT="\"$(git rev-parse HEAD)\"" \
  src/cli.ts --outfile mycli

Script d'automatisation de compilation

Créez un script de compilation qui injecte automatiquement les métadonnées de compilation :

// build.ts
import { $ } from "bun";

const version = await $`git describe --tags --always`.text();
const buildTime = new Date().toISOString();
const gitCommit = await $`git rev-parse HEAD`.text();

await Bun.build({
  entrypoints: ["./src/cli.ts"],
  outdir: "./dist",
  define: {
    BUILD_VERSION: JSON.stringify(version.trim()),
    BUILD_TIME: JSON.stringify(buildTime),
    GIT_COMMIT: JSON.stringify(gitCommit.trim()),
  },
});

console.log(`Compilé avec la version ${version.trim()}`);

---

Considérations importantes

Format des valeurs

Les valeurs doivent être du JSON valide qui sera analysé et intégré comme expressions JavaScript :

# ✅ Les chaînes doivent être citées en JSON
--define VERSION='"1.0.0"'

# ✅ Les nombres sont des littéraux JSON
--define PORT=3000

# ✅ Les booléens sont des littéraux JSON
--define DEBUG=true

# ✅ Les objets et tableaux (utilisez des guillemets simples pour envelopper le JSON)
--define 'CONFIG={"host":"localhost","port":3000}'

# ✅ Les tableaux fonctionnent aussi
--define 'FEATURES=["auth","billing","analytics"]'

# ❌ Cela ne fonctionnera pas - guillemets manquants autour de la chaîne
--define VERSION=1.0.0

Clés de propriété

Vous pouvez utiliser des motifs d'accès aux propriétés comme clés, pas seulement des identifiants simples :

# ✅ Remplacer process.env.NODE_ENV par "production"
--define 'process.env.NODE_ENV="production"'

# ✅ Remplacer process.env.API_KEY par la clé réelle
--define 'process.env.API_KEY="abc123"'

# ✅ Remplacer les propriétés imbriquées
--define 'window.myApp.version="1.0.0"'

# ✅ Remplacer l'accès au tableau
--define 'process.argv[2]="--production"'

Ceci est particulièrement utile pour les variables d'environnement :

// Avant compilation
if (process.env.NODE_ENV === "production") {
  console.log("Mode production");
}

// Après compilation avec --define 'process.env.NODE_ENV="production"'
if ("production" === "production") {
  console.log("Mode production");
}

// Après optimisation
console.log("Mode production");

Déclarations TypeScript

Pour les projets TypeScript, déclarez vos constantes pour éviter les erreurs de type :

// types/build-constants.d.ts
declare const BUILD_VERSION: string;
declare const BUILD_TIME: string;
declare const NODE_ENV: "development" | "staging" | "production";
declare const DEBUG: boolean;

Compatibilité multiplateforme

Lors de la compilation pour plusieurs plates-formes, les constantes fonctionnent de la même manière :

# Linux
bun build --compile --target=bun-linux-x64 --define PLATFORM='"linux"' src/app.ts --outfile app-linux

# macOS
bun build --compile --target=bun-darwin-x64 --define PLATFORM='"darwin"' src/app.ts --outfile app-macos

# Windows
bun build --compile --target=bun-windows-x64 --define PLATFORM='"windows"' src/app.ts --outfile app-windows.exe

---

Voir aussi

• Définir des constantes au moment de l'exécution - Utilisation de --define avec bun run
• Compilation d'exécutables - Guide complet de bun build --compile
• API Bundler - Documentation complète du bundler y compris l'option define