I cataloghi in Bun forniscono un modo semplice per condividere versioni comuni delle dipendenze tra più pacchetti in un monorepo. Invece di specificare ripetutamente le stesse versioni in ogni pacchetto dello spazio di lavoro, le definisci una volta nel package.json radice e le riferisci coerentemente in tutto il tuo progetto.

Panoramica

A differenza della gestione tradizionale delle dipendenze dove ogni pacchetto dello spazio di lavoro deve specificare indipendentemente le versioni, i cataloghi ti permettono di:

1. Definire cataloghi di versioni nel package.json radice
2. Riferire queste versioni con un semplice protocollo catalog:
3. Aggiornare tutti i pacchetti simultaneamente cambiando la versione in un solo posto

Questo è particolarmente utile in grandi monorepo dove dozzine di pacchetti devono usare la stessa versione di dipendenze chiave.

Come Usare i Cataloghi

Esempio di Struttura delle Directory

Considera un monorepo con la seguente struttura:

my-monorepo/
├── package.json
├── bun.lock
└── packages/
    ├── app/
    │   └── package.json
    ├── ui/
    │   └── package.json
    └── utils/
        └── package.json

1. Definire i Cataloghi nel Package.json Radice

Nel tuo package.json di livello radice, aggiungi un campo catalog o catalogs nell'oggetto workspaces:

{
  "name": "my-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0"
    },
    "catalogs": {
      "testing": {
        "jest": "30.0.0",
        "testing-library": "14.0.0"
      }
    }
  }
}

Se metti catalog o catalogs al livello superiore del file package.json, funzionerà ugualmente.

2. Riferire le Versioni del Catalogo nei Pacchetti dello Spazio di Lavoro

Nei tuoi pacchetti dello spazio di lavoro, usa il protocollo catalog: per riferire le versioni:

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "jest": "catalog:testing"
  }
}

{
  "name": "ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "testing-library": "catalog:testing"
  }
}

3. Eseguire Bun Install

Esegui bun install per installare tutte le dipendenze secondo le versioni del catalogo.

Catalog vs Catalogs

Bun supporta due modi per definire i cataloghi:

1. catalog (singolare): Un catalogo predefinito singolo per dipendenze comunemente usate

   "catalog": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   }

   Riferisci semplicemente con catalog::

   "dependencies": {
     "react": "catalog:"
   }

2. catalogs (plurale): Multipli cataloghi nominati per raggruppare le dipendenze

   "catalogs": {
     "testing": {
       "jest": "30.0.0"
     },
     "ui": {
       "tailwind": "4.0.0"
     }
   }

   Riferisci con catalog:<nome>:

   "dependencies": {
     "jest": "catalog:testing",
     "tailwind": "catalog:ui"
   }

Benefici dell'Uso dei Cataloghi

• Coerenza: Assicura che tutti i pacchetti usino la stessa versione di dipendenze critiche
• Manutenzione: Aggiorna una versione di dipendenza in un solo posto invece che attraverso più file package.json
• Chiarezza: Rende ovvio quali dipendenze sono standardizzate nel tuo monorepo
• Semplicità: Non c'è bisogno di strategie complesse di risoluzione delle versioni o strumenti esterni

Esempio del Mondo Reale

Ecco un esempio più completo per un'applicazione React:

Package.json radice

{
  "name": "react-monorepo",
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^19.0.0",
      "react-dom": "^19.0.0",
      "react-router-dom": "^6.15.0"
    },
    "catalogs": {
      "build": {
        "webpack": "5.88.2",
        "babel": "7.22.10"
      },
      "testing": {
        "jest": "29.6.2",
        "react-testing-library": "14.0.0"
      }
    }
  },
  "devDependencies": {
    "typescript": "5.1.6"
  }
}

{
  "name": "app",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:",
    "react-router-dom": "catalog:",
    "@monorepo/ui": "workspace:*",
    "@monorepo/utils": "workspace:*"
  },
  "devDependencies": {
    "webpack": "catalog:build",
    "babel": "catalog:build",
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/ui",
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing",
    "react-testing-library": "catalog:testing"
  }
}

{
  "name": "@monorepo/utils",
  "dependencies": {
    "react": "catalog:"
  },
  "devDependencies": {
    "jest": "catalog:testing"
  }
}

Aggiornare le Versioni

Per aggiornare le versioni in tutti i pacchetti, cambia semplicemente la versione nel package.json radice:

"catalog": {
  "react": "^19.1.0",  // Aggiornato da ^19.0.0
  "react-dom": "^19.1.0"  // Aggiornato da ^19.0.0
}

Poi esegui bun install per aggiornare tutti i pacchetti.

Integrazione con il Lockfile

Il lockfile di Bun tiene traccia delle versioni del catalogo, rendendo facile garantire installazioni coerenti in diversi ambienti. Il lockfile include:

• Le definizioni del catalogo dal tuo package.json
• La risoluzione di ogni dipendenza catalogata

{
  "lockfileVersion": 1,
  "workspaces": {
    "": {
      "name": "react-monorepo",
    },
    "packages/app": {
      "name": "app",
      "dependencies": {
        "react": "catalog:",
        "react-dom": "catalog:",
        ...
      },
    },
    ...
  },
  "catalog": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    ...
  },
  "catalogs": {
    "build": {
      "webpack": "5.88.2",
      ...
    },
    ...
  },
  "packages": {
    ...
  }
}

Limitazioni e Casi Particolari

• I riferimenti al catalogo devono corrispondere a una dipendenza definita in catalog o in uno dei catalogs nominati
• Stringhe vuote e spazi bianchi nei nomi dei cataloghi vengono ignorati (trattati come catalogo predefinito)
• Versioni di dipendenze non valide nei cataloghi non riusciranno a risolversi durante bun install
• I cataloghi sono disponibili solo all'interno degli spazi di lavoro; non possono essere usati fuori dal monorepo

Il sistema di cataloghi di Bun fornisce un modo potente ma semplice per mantenere la coerenza nel tuo monorepo senza introdurre complessità aggiuntiva nel tuo flusso di lavoro.

Pubblicazione

Quando esegui bun publish o bun pm pack, Bun sostituisce automaticamente i riferimenti catalog: nel tuo package.json con i numeri di versione risolti. Il pacchetto pubblicato include stringhe semver regolari e non dipende più dalle tue definizioni di catalogo.