Il flag --define può essere usato con bun build e bun build --compile per inserire costanti a tempo di build nella tua applicazione. Questo è particolarmente utile per incorporare metadati come versioni di build, timestamp o flag di configurazione direttamente nei tuoi eseguibili compilati.

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

---

Perché usare le costanti a tempo di build?

Le costanti a tempo di build sono incorporate direttamente nel codice compilato, rendendole:

• Zero overhead a runtime - Nessuna ricerca di variabili d'ambiente o letture di file
• Immutabili - I valori sono incorporati nel binary al momento della compilazione
• Ottimizzabili - L'eliminazione del codice morto può rimuovere rami non utilizzati
• Sicure - Nessuna dipendenza esterna o file di configurazione da gestire

Questo è simile a gcc -D o #define in C/C++, ma per JavaScript/TypeScript.

---

Uso base

Con bun build

# Bundle con costanti a tempo di build
bun build --define BUILD_VERSION='"1.0.0"' --define NODE_ENV='"production"' src/index.ts --outdir ./dist

Con bun build --compile

# Compila in eseguibile con costanti a tempo di build
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",
  },
});

---

Casi d'uso comuni

Informazioni di versione

Incorpora versione e metadati di build direttamente nel tuo eseguibile:

// Queste costanti vengono sostituite al momento della build
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

Flag di funzionalità

Usa le costanti a tempo di build per abilitare/disabilitare funzionalità:

// Sostituito al momento della build
declare const ENABLE_ANALYTICS: boolean;
declare const ENABLE_DEBUG: boolean;

function trackEvent(event: string) {
  if (ENABLE_ANALYTICS) {
    // Questo intero blocco viene rimosso se ENABLE_ANALYTICS è false
    console.log("Tracciamento:", event);
  }
}

if (ENABLE_DEBUG) {
  console.log("Modalità debug abilitata");
}

# Build produzione - analytics abilitato, debug disabilitato
bun build --compile --define ENABLE_ANALYTICS=true --define ENABLE_DEBUG=false src/app.ts --outfile app-prod

# Build sviluppo - entrambi abilitati
bun build --compile --define ENABLE_ANALYTICS=false --define ENABLE_DEBUG=true src/app.ts --outfile app-dev

Configurazione

Sostituisci oggetti di configurazione al momento della build:

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

// CONFIG viene sostituito con l'oggetto effettivo al momento della build
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

---

Pattern avanzati

Build specifiche per ambiente

Crea eseguibili diversi per ambienti diversi:

{
  "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"
  }
}

Usare comandi shell per valori dinamici

Genera costanti a tempo di build da comandi shell:

# Usa git per ottenere il commit corrente e il timestamp
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 di automazione della build

Crea uno script di build che inserisce automaticamente i metadati di build:

// 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(`Build eseguita con versione ${version.trim()}`);

---

Considerazioni importanti

Formato dei valori

I valori devono essere JSON validi che verranno parsati e incorporati come espressioni JavaScript:

# ✅ Le stringhe devono essere quotate JSON
--define VERSION='"1.0.0"'

# ✅ I numeri sono letterali JSON
--define PORT=3000

# ✅ I booleani sono letterali JSON
--define DEBUG=true

# ✅ Oggetti e array (usa virgolette singole per racchiudere il JSON)
--define 'CONFIG={"host":"localhost","port":3000}'

# ✅ Anche gli array funzionano
--define 'FEATURES=["auth","billing","analytics"]'

# ❌ Questo non funziona - mancano le virgolette attorno alla stringa
--define VERSION=1.0.0

Chiavi delle proprietà

Puoi usare pattern di accesso alle proprietà come chiavi, non solo identificatori semplici:

# ✅ Sostituisci process.env.NODE_ENV con "production"
--define 'process.env.NODE_ENV="production"'

# ✅ Sostituisci process.env.API_KEY con la chiave effettiva
--define 'process.env.API_KEY="abc123"'

# ✅ Sostituisci proprietà annidate
--define 'window.myApp.version="1.0.0"'

# ✅ Sostituisci accesso ad array
--define 'process.argv[2]="--production"'

Questo è particolarmente utile per le variabili d'ambiente:

// Prima della compilazione
if (process.env.NODE_ENV === "production") {
  console.log("Modalità produzione");
}

// Dopo la compilazione con --define 'process.env.NODE_ENV="production"'
if ("production" === "production") {
  console.log("Modalità produzione");
}

// Dopo l'ottimizzazione
console.log("Modalità produzione");

Dichiarazioni TypeScript

Per progetti TypeScript, dichiara le tue costanti per evitare errori di tipo:

// 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à cross-platform

Quando si compila per più piattaforme, le costanti funzionano allo stesso modo:

# 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

---

Correlati

• Definire costanti a runtime - Usare --define con bun run
• Costruire eseguibili - Guida completa a bun build --compile
• API Bundler - Documentazione completa del bundler inclusa l'opzione define