import Install from "/it/snippets/cli/install.mdx";

Utilizzo Base

bun install react
bun install react@19.1.1 # versione specifica
bun install react@latest # tag specifico

La CLI bun contiene un package manager compatibile con Node.js progettato per essere un sostituto drasticamente più veloce di npm, yarn, e pnpm. È uno strumento autonomo che funzionerà in progetti Node.js preesistenti; se il tuo progetto ha un package.json, bun install può aiutarti ad accelerare il tuo flusso di lavoro.

NOTE

⚡️ 25 volte più veloce — Passa da npm install a bun install in qualsiasi progetto Node.js per rendere le tue installazioni fino a 25 volte più veloci.

Per utenti Linux

La versione minima raccomandata del kernel Linux è 5.6. Se sei su kernel Linux 5.1 - 5.5, bun install funzionerà, ma le richieste HTTP saranno lente a causa della mancanza di supporto per l'operazione connect() di io_uring.

Se stai usando Ubuntu 20.04, ecco come installare un kernel più recente:

# Se questo restituisce una versione >= 5.6, non devi fare nulla
uname -r

# Installa il kernel hardware enablement ufficiale di Ubuntu
sudo apt install --install-recommends linux-generic-hwe-20.04

Per installare tutte le dipendenze di un progetto:

bun install

Eseguendo bun install:

• Installa tutte le dependencies, devDependencies, e optionalDependencies. Bun installerà peerDependencies per impostazione predefinita.
• Esegue gli script {pre|post}install e {pre|post}prepare del tuo progetto al momento appropriato. Per ragioni di sicurezza Bun non esegue script del ciclo di vita delle dipendenze installate.
• Scrive un lockfile bun.lock nella radice del progetto.

---

Logging

Per modificare la verbosità del logging:

bun install --verbose # logging debug
bun install --silent  # nessun logging

---

Script del ciclo di vita

Diversamente da altri client npm, Bun non esegue script arbitrari del ciclo di vita come postinstall per le dipendenze installate. Eseguire script arbitrari rappresenta un potenziale rischio per la sicurezza.

Per dire a Bun di consentire script del ciclo di vita per un particolare pacchetto, aggiungi il pacchetto a trustedDependencies nel tuo package.json.

{
  "name": "my-app",
  "version": "1.0.0",
  "trustedDependencies": ["my-trusted-package"] 
}

Poi reinstalla il pacchetto. Bun leggerà questo campo ed eseguirà script del ciclo di vita per my-trusted-package.

Gli script del ciclo di vita verranno eseguiti in parallelo durante l'installazione. Per regolare il numero massimo di script concorrenti, usa il flag --concurrent-scripts. Il predefinito è due volte il conteggio cpu riportato o GOMAXPROCS.

bun install --concurrent-scripts 5

Bun ottimizza automaticamente gli script postinstall per pacchetti popolari (come esbuild, sharp, ecc.) determinando quali script devono essere eseguiti. Per disabilitare queste ottimizzazioni:

BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install

---

Workspaces

Bun supporta "workspaces" in package.json. Per la documentazione completa riferisciti a Package manager > Workspaces.

{
  "name": "my-app",
  "version": "1.0.0",
  "workspaces": ["packages/*"], 
  "dependencies": {
    "preact": "^10.5.13"
  }
}

---

Installare dipendenze per pacchetti specifici

In un monorepo, puoi installare le dipendenze per un sottoinsieme di pacchetti usando il flag --filter.

# Installa dipendenze per tutti gli workspaces tranne `pkg-c`
bun install --filter '!pkg-c'

# Installa dipendenze solo per `pkg-a` in `./packages/pkg-a`
bun install --filter './packages/pkg-a'

Per maggiori informazioni sul filtraggio con bun install, riferisciti a Package Manager > Filtraggio

---

Override e risoluzioni

Bun supporta gli "overrides" di npm e le "resolutions" di Yarn in package.json. Questi sono meccanismi per specificare un intervallo di versioni per le metadipendenze—le dipendenze delle tue dipendenze. Riferisciti a Package manager > Override e risoluzioni per la documentazione completa.

{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  },
  "overrides": { 
    "bar": "~4.4.0"
  } 
}

---

Pacchetti globali

Per installare un pacchetto globalmente, usa il flag -g/--global. Tipicamente questo è usato per installare strumenti da riga di comando.

bun install --global cowsay # o `bun install -g cowsay`
cowsay "Bun!"

 ______
< Bun! >
 ------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

---

Modalità produzione

Per installare in modalità produzione (cioè senza devDependencies o optionalDependencies):

bun install --production

Per installazioni riproducibili, usa --frozen-lockfile. Questo installerà le versioni esatte di ogni pacchetto specificate nel lockfile. Se il tuo package.json non è d'accordo con bun.lock, Bun uscirà con un errore. Il lockfile non verrà aggiornato.

bun install --frozen-lockfile

Per maggiori informazioni sul lockfile di Bun bun.lock, riferisciti a Package manager > Lockfile.

---

Omettere dipendenze

Per omettere dipendenze dev, peer o opzionali usa il flag --omit.

# Escludi "devDependencies" dall'installazione. Questo si applicherà al
# pacchetto radice e agli workspaces se esistono. Le dipendenze transitive
# non avranno "devDependencies".
bun install --omit dev

# Installa solo dipendenze da "dependencies"
bun install --omit=dev --omit=peer --omit=optional

---

Dry run

Per eseguire un dry run (cioè non installare effettivamente nulla):

bun install --dry-run

---

Dipendenze non-npm

Bun supporta l'installazione di dipendenze da Git, GitHub, e tarball ospitati localmente o remotamente. Per la documentazione completa riferisciti a Package manager > Dipendenze Git, GitHub e tarball.

{
  "dependencies": {
    "dayjs": "git+https://github.com/iamkun/dayjs.git",
    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
    "moment": "git@github.com:moment/moment.git",
    "zod": "github:colinhacks/zod",
    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
    "bun-types": "npm:@types/bun"
  }
}

---

Strategie di installazione

Bun supporta due strategie di installazione pacchetti che determinano come le dipendenze sono organizzate in node_modules:

Installazioni hoisted

L'approccio tradizionale npm/Yarn che appiattisce le dipendenze in una directory node_modules condivisa:

bun install --linker hoisted

Installazioni isolate

Un approccio simile a pnpm che crea un isolamento rigoroso delle dipendenze per prevenire dipendenze fantasma:

bun install --linker isolated

Le installazioni isolate creano un archivio pacchetti centrale in node_modules/.bun/ con symlink nel node_modules di livello superiore. Questo assicura che i pacchetti possano accedere solo alle loro dipendenze dichiarate.

Strategia predefinita

La strategia di linker predefinita dipende dal fatto che tu stia iniziando da zero o abbia un progetto esistente:

• Nuovi workspaces/monorepo: isolated (previene dipendenze fantasma)
• Nuovi progetti a pacchetto singolo: hoisted (comportamento npm tradizionale)
• Progetti esistenti (creati pre-v1.3.2): hoisted (preserva la compatibilità con le versioni precedenti)

Il predefinito è controllato da un campo configVersion nel tuo lockfile. Per una spiegazione dettagliata, vedi Package manager > Installazioni isolate.

---

Età minima di rilascio

Per proteggersi dagli attacchi alla supply chain dove pacchetti dannosi vengono pubblicati rapidamente, puoi configurare un requisito di età minima per i pacchetti npm. Le versioni dei pacchetti pubblicate più recentemente della soglia specificata (in secondi) verranno filtrate durante l'installazione.

# Installa solo versioni di pacchetti pubblicate almeno 3 giorni fa
bun add @types/bun --minimum-release-age 259200 # secondi

Puoi anche configurare questo in bunfig.toml:

[install]
# Installa solo versioni di pacchetti pubblicate almeno 3 giorni fa
minimumReleaseAge = 259200 # secondi

# Escludi pacchetti attendibili dall'età minima
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Quando il filtro dell'età minima è attivo:

• Influenza solo la nuova risoluzione dei pacchetti - i pacchetti esistenti in bun.lock rimangono invariati
• Tutte le dipendenze (dirette e transitive) vengono filtrate per soddisfare il requisito di età durante la risoluzione
• Quando le versioni sono bloccate dal filtro dell'età, un controllo di stabilità rileva pattern di correzioni bug rapidi
  • Se più versioni sono state pubblicate vicine appena fuori dal filtro dell'età, estende il filtro per saltare quelle versioni potenzialmente instabili e seleziona una versione più vecchia e matura
  • Cerca fino a 7 giorni dopo il filtro dell'età, tuttavia se trova ancora rilasci rapidi ignora il controllo di stabilità
  • Le richieste di versione esatte (come package@1.1.1) rispettano comunque il filtro dell'età ma bypassano il controllo di stabilità
• Le versioni senza un campo time sono trattate come superanti il controllo dell'età (il registro npm dovrebbe fornire sempre timestamp)

Per una scansione di sicurezza più avanzata, inclusa l'integrazione con servizi e filtraggio personalizzato, vedi Package manager > API Scanner di Sicurezza.

---

Configurazione

Configurare bun install con bunfig.toml

bunfig.toml viene cercato nei seguenti percorsi su bun install, bun remove, e bun add:

1. $XDG_CONFIG_HOME/.bunfig.toml o $HOME/.bunfig.toml
2. ./bunfig.toml

Se entrambi sono trovati, i risultati vengono uniti.

La configurazione con bunfig.toml è opzionale. Bun cerca di essere zero configurazione in generale, ma non è sempre possibile. Il comportamento predefinito di bun install può essere configurato in bunfig.toml. I valori predefiniti sono mostrati sotto.

[install]

# se installare optionalDependencies
optional = true

# se installare devDependencies
dev = true

# se installare peerDependencies
peer = true

# equivalente al flag `--production`
production = false

# equivalente al flag `--save-text-lockfile`
saveTextLockfile = false

# equivalente al flag `--frozen-lockfile`
frozenLockfile = false

# equivalente al flag `--dry-run`
dryRun = false

# equivalente al flag `--concurrent-scripts`
concurrentScripts = 16 # (conteggio cpu o GOMAXPROCS) x2

# strategia di installazione: "hoisted" o "isolated"
# il predefinito dipende dal configVersion del lockfile e workspaces:
# - configVersion = 1: "isolated" se usa workspaces, altrimenti "hoisted"
# - configVersion = 0: "hoisted"
linker = "hoisted"


# configurazione età minima
minimumReleaseAge = 259200 # secondi
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

Configurare con variabili d'ambiente

Le variabili d'ambiente hanno una priorità più alta di bunfig.toml.

Nome	Descrizione
BUN_CONFIG_REGISTRY	Imposta un registro npm (predefinito: https://registry.npmjs.org)
BUN_CONFIG_TOKEN	Imposta un token di autenticazione (attualmente non fa nulla)
BUN_CONFIG_YARN_LOCKFILE	Salva un yarn.lock in stile Yarn v1
BUN_CONFIG_LINK_NATIVE_BINS	Punta bin in package.json a una dipendenza specifica per piattaforma
BUN_CONFIG_SKIP_SAVE_LOCKFILE	Non salvare un lockfile
BUN_CONFIG_SKIP_LOAD_LOCKFILE	Non caricare un lockfile
BUN_CONFIG_SKIP_INSTALL_PACKAGES	Non installare alcun pacchetto

Bun cerca sempre di usare il metodo di installazione più veloce disponibile per la piattaforma target. Su macOS, è clonefile e su Linux, è hardlink. Puoi cambiare quale metodo di installazione viene usato con il flag --backend. Quando non disponibile o su errore, clonefile e hardlink ricadono su un'implementazione specifica per piattaforma di copia file.

Bun archivia i pacchetti installati da npm in ~/.bun/install/cache/${name}@${version}. Nota che se la versione semver ha un tag build o pre, viene sostituito con un hash di quel valore. Questo è per ridurre le possibilità di errori da percorsi di file lunghi, ma sfortunatamente complica capire dove un pacchetto è stato installato su disco.

Quando la cartella node_modules esiste, prima di installare, Bun controlla se il "name" e "version" in package/package.json nella cartella node_modules prevista corrisponde al name e version previsti. Questo è come determina se dovrebbe installare. Usa un parser JSON personalizzato che interrompe l'analisi non appena trova "name" e "version".

Quando un bun.lock non esiste o package.json ha cambiato dipendenze, i tarball vengono scaricati ed estratti eager durante la risoluzione.

Quando un bun.lock esiste e package.json non è cambiato, Bun scarica le dipendenze mancanti in modo lazy. Se il pacchetto con un name e version corrispondenti esiste già nella posizione prevista all'interno di node_modules, Bun non tenterà di scaricare il tarball.

CI/CD

Usa l'azione ufficiale oven-sh/setup-bun per installare bun in una pipeline GitHub Actions:

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun install
      - name: Build app
        run: bun run build

Per ambienti CI/CD che vogliono imporre build riproducibili, usa bun ci per far fallire la build se il package.json non è sincronizzato con il lockfile:

bun ci

Questo è equivalente a bun install --frozen-lockfile. Installa versioni esatte da bun.lock e fallisce se package.json non corrisponde al lockfile. Per usare bun ci o bun install --frozen-lockfile, devi commitare bun.lock al controllo versione.

E invece di eseguire bun install, esegui bun ci.

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun ci
      - name: Build app
        run: bun run build

Dipendenze specifiche per piattaforma?

bun archivia i valori normalizzati cpu e os da npm nel lockfile, insieme ai pacchetti risolti. Salta il download, l'estrazione e l'installazione di pacchetti disabilitati per il target corrente a runtime. Questo significa che il lockfile non cambierà tra piattaforme/architetture anche se i pacchetti alla fine installati cambiano.

Flag --cpu e --os

Puoi sovrascrivere la piattaforma target per la selezione dei pacchetti:

bun install --cpu=x64 --os=linux

Questo installa pacchetti per la piattaforma specificata invece del sistema corrente. Utile per build cross-platform o quando si preparano deployment per ambienti diversi.

Valori accettati per --cpu: arm64, x64, ia32, ppc64, s390x

Valori accettati per --os: linux, darwin, win32, freebsd, openbsd, sunos, aix

Dipendenze peer?

Le dipendenze peer sono gestite in modo simile a yarn. bun install installerà automaticamente le dipendenze peer. Se la dipendenza è marcata opzionale in peerDependenciesMeta, una dipendenza esistente verrà scelta se possibile.

Lockfile

bun.lock è il formato lockfile di Bun. Vedi il nostro blogpost sul lockfile di testo.

Prima di Bun 1.2, il lockfile era binario e chiamato bun.lockb. I lockfile vecchi possono essere aggiornati al nuovo formato eseguendo bun install --save-text-lockfile --frozen-lockfile --lockfile-only, e poi eliminando bun.lockb.

Cache

Per eliminare la cache:

bun pm cache rm
# o
rm -rf ~/.bun/install/cache

Backend specifici per piattaforma

bun install usa diverse system call per installare dipendenze a seconda della piattaforma. Questa è un'ottimizzazione delle prestazioni. Puoi forzare un backend specifico con il flag --backend.

hardlink è il backend predefinito su Linux. I benchmark hanno mostrato che è il più veloce su Linux.

rm -rf node_modules
bun install --backend hardlink

clonefile è il backend predefinito su macOS. I benchmark hanno mostrato che è il più veloce su macOS. È disponibile solo su macOS.

rm -rf node_modules
bun install --backend clonefile

clonefile_each_dir è simile a clonefile, eccetto che clona ogni file individualmente per directory. È disponibile solo su macOS e tende a essere più lento di clonefile. Diversamente da clonefile, questo non clona ricorsivamente le sottodirectory in una system call.

rm -rf node_modules
bun install --backend clonefile_each_dir

copyfile è il fallback usato quando uno qualsiasi dei precedenti fallisce, ed è il più lento. su macOS, usa fcopyfile() e su linux usa copy_file_range().

rm -rf node_modules
bun install --backend copyfile

symlink è tipicamente usato solo per dipendenze file: (e eventualmente link:) internamente. Per prevenire loop infiniti, salta il collegamento simbolico della cartella node_modules.

Se installi con --backend=symlink, Node.js non risolverà i node_modules delle dipendenze a meno che ogni dipendenza abbia la propria cartella node_modules o passi --preserve-symlinks a node o bun. Vedi documentazione di Node.js su --preserve-symlinks.

rm -rf node_modules
bun install --backend symlink
bun --preserve-symlinks ./my-file.js
node --preserve-symlinks ./my-file.js # https://nodejs.org/api/cli.html#--preserve-symlinks

Metadati del registro npm

Bun usa un formato binario per memorizzare nella cache le risposte del registro NPM. Questo si carica molto più velocemente di JSON e tende a essere più piccolo su disco. Vedrai questi file in ~/.bun/install/cache/*.npm. Il pattern del nome file è ${hash(packageName)}.npm. È un hash così che non c'è bisogno di creare directory extra per pacchetti con scope.

L'uso di Cache-Control di Bun ignora Age. Questo migliora le prestazioni, ma significa che bun può essere indietro di circa 5 minuti per ricevere i metadati della versione del pacchetto più recente da npm.

Migrazione pnpm

Bun migra automaticamente i progetti da pnpm a bun. Quando viene rilevato un file pnpm-lock.yaml e nessun file bun.lock esiste, Bun migrerà automaticamente il lockfile in bun.lock durante l'installazione. Il file pnpm-lock.yaml originale rimane non modificato.

bun install

Nota: La migrazione viene eseguita solo quando bun.lock è assente. Attualmente non c'è un flag per rinunciare alla migrazione pnpm.

Il processo di migrazione gestisce:

Migrazione Lockfile

• Converte pnpm-lock.yaml in formato bun.lock
• Preserva versioni dei pacchetti e informazioni di risoluzione
• Mantiene relazioni di dipendenza e dipendenze peer
• Gestisce dipendenze patchate con hash di integrità

Configurazione Workspace

Quando esiste un file pnpm-workspace.yaml, Bun migra le impostazioni workspace nel tuo package.json radice:

packages:
  - "apps/*"
  - "packages/*"

catalog:
  react: ^18.0.0
  typescript: ^5.0.0

catalogs:
  build:
    webpack: ^5.0.0
    babel: ^7.0.0

L'elenco dei pacchetti workspace e i cataloghi vengono spostati nel campo workspaces in package.json:

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": {
      "react": "^18.0.0",
      "typescript": "^5.0.0"
    },
    "catalogs": {
      "build": {
        "webpack": "^5.0.0",
        "babel": "^7.0.0"
      }
    }
  }
}

Dipendenze Catalog

Le dipendenze che usano il protocollo catalog: di pnpm sono preservate:

{
  "dependencies": {
    "react": "catalog:",
    "webpack": "catalog:build"
  }
}

Migrazione Configurazione

La seguente configurazione pnpm viene migrata da pnpm-lock.yaml e pnpm-workspace.yaml:

• Override: Spostati da pnpm.overrides a overrides di livello radice in package.json
• Dipendenze Patchate: Spostate da pnpm.patchedDependencies a patchedDependencies di livello radice in package.json
• Override Workspace: Applicati da pnpm-workspace.yaml a package.json radice

Requisiti

• Richiede versione lockfile pnpm 7 o superiore
• I pacchetti workspace devono avere un campo name nel loro package.json
• Tutte le voci catalog riferite dalle dipendenze devono esistere nella definizione dei cataloghi

Dopo la migrazione, puoi rimuovere in sicurezza i file pnpm-lock.yaml e pnpm-workspace.yaml.