> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK TypeScript : guide d’intégration de bibliothèques tierces

> Intégrez des bibliothèques tierces au SDK TypeScript de Weave

Ce guide explique comment intégrer des bibliothèques tierces (par exemple OpenAI) au SDK TypeScript de Weave. Il s’adresse aux développeurs TypeScript qui souhaitent que Weave trace automatiquement les appels aux bibliothèques prises en charge dans leur application.

Weave prend en charge l’instrumentation automatique, ce qui simplifie la configuration et réduit le besoin de configuration manuelle.

<Warning>
  **Qu’est-ce qui a changé ?**
  Depuis la [PR #4554](https://github.com/wandb/weave/pull/4554), Weave effectue automatiquement le patching des bibliothèques prises en charge, comme OpenAI, lors de son chargement. Vous n’avez donc plus besoin de les encapsuler manuellement :

  ```ts twoslash lines theme={null}
  // @noErrors
  weave.wrapOpenAI(new OpenAI());
  ```

  Weave s’en charge automatiquement dans la plupart des cas. Cependant, des [cas limites](#advanced-usage) peuvent survenir.
</Warning>

<div id="use-weave-integrations-with-your-typescript-project">
  ## Utilisez les intégrations Weave avec votre projet TypeScript
</div>

Les sections suivantes expliquent comment déterminer le système de modules utilisé par votre projet, puis configurer ce projet afin que Weave puisse instrumenter automatiquement les bibliothèques tierces prises en charge. Les projets TypeScript peuvent utiliser le système de modules CommonJS ou ESM, et la configuration requise diffère légèrement selon le système utilisé.

<div id="if-youre-unsure-which-type-of-project-you-have">
  ### Si vous ne savez pas quel type de projet vous avez
</div>

Si vous exécutez directement un fichier TypeScript avec un outil tel que :

```bash theme={null}
npx tsx test.ts
```

le système de modules peut être déterminé implicitement par votre environnement. Pour garantir un comportement cohérent, définissez explicitement les fichiers `package.json` et `tsconfig.json`.

Pour déterminer si un projet utilise CommonJS ou ESM, vérifiez le champ `type` dans `package.json` :

```json theme={null}
"type": "module"
```

* Si `type` vaut `"module"`, le projet utilise ESM.
* Si le champ `type` est absent ou défini sur `"commonjs"`, le projet utilise CommonJS par défaut.

<div id="set-up-a-commonjs-project">
  ### Configurer un projet CommonJS
</div>

Pour les projets CommonJS, l’instrumentation automatique fonctionne sans configuration supplémentaire.

Pour configurer votre projet en CommonJS :

1. Créez ou mettez à jour votre `package.json` :

   ```json theme={null}
   {
     "type": "commonjs"
   }
   ```

2. Créez un `tsconfig.json` avec des paramètres compatibles avec CommonJS :

   ```json theme={null}
   {
     "compilerOptions": {
       "module": "CommonJS",
       "target": "es2022",
       "rootDir": ".",
       "outDir": "dist"
     }
   }
   ```

   Ces paramètres configurent TypeScript pour compiler en CommonJS :

   * `module: "CommonJS"`. Compile les modules au format CommonJS (`require` ou `module.exports`).
     Pour plus de détails sur cette option du compilateur, voir [TypeScript - Module](https://www.typescriptlang.org/tsconfig/#module).

   * `target: "es2022"` (recommandé). Génère du JavaScript moderne compatible avec les versions récentes de Node.js.
     Pour plus de détails sur cette option du compilateur, voir [TypeScript - Target](https://www.typescriptlang.org/tsconfig/#target).

   * `rootDir: "."`. Considère le répertoire contenant `tsconfig.json` comme la racine de vos fichiers d’entrée. TypeScript l’utilise avec `outDir` pour reproduire la structure de votre dossier source dans le résultat généré.
     Pour plus de détails sur cette option du compilateur, voir [TypeScript - Root Dir](https://www.typescriptlang.org/tsconfig/#rootDir).

   * `outDir: "dist"`. Écrit le JavaScript généré et les autres sorties du compilateur dans le dossier `dist`.
     Pour plus de détails sur cette option du compilateur, voir [TypeScript - Out Dir](https://www.typescriptlang.org/tsconfig/#outDir).

3. Installez Weave et toutes les autres bibliothèques requises :

   ```bash theme={null}
   npm install weave
   ```

4. Compilez votre fichier TypeScript.

   Pour un fichier d’exemple `test.ts` :

   ```bash theme={null}
   npx tsc
   ```

   Cela compile le fichier en `dist/test.js`.

5. Exécutez le fichier compilé avec Node.js :

   ```bash theme={null}
   node dist/test.js
   ```

Votre projet CommonJS est maintenant configuré pour que Weave instrumente automatiquement les bibliothèques prises en charge lors de l’exécution de votre code. Comme CommonJS utilise le chargeur de modules `require` de Node.js, Weave peut instrumenter automatiquement les bibliothèques prises en charge sans nécessiter l’option `--import` utilisée dans les projets ESM.

<div id="set-up-an-esm-project">
  ### Configurer un projet ESM
</div>

Pour utiliser Weave avec un projet TypeScript ESM, configurez votre projet pour le mode ESM de Node.js, compilez votre code, puis démarrez Node.js avec l’option `--import` afin que Weave puisse enregistrer son instrumentation avant le chargement des autres modules.

Pour configurer votre projet pour ESM :

1. Créez ou mettez à jour votre `package.json` :

   ```json theme={null}
   {
     "type": "module"
   }
   ```

2. Créez un `tsconfig.json` avec des paramètres ESM compatibles avec Node.js :

   ```json theme={null}
   {
     "compilerOptions": {
       "module": "nodenext",
       "moduleResolution": "nodenext",
       "target": "es2022",
       "rootDir": ".",
       "outDir": "dist"
     }
   }
   ```

   Ces paramètres configurent TypeScript pour compiler vers un ESM Node.js moderne :

   * **`module: "nodenext"`** — Compile les modules selon la sémantique ESM de Node.js.
     Pour plus de détails sur cette option du compilateur, voir [TypeScript - Module](https://www.typescriptlang.org/tsconfig/#module).

   * **`moduleResolution: "nodenext"`** — Garantit que la résolution des modules suit les règles ESM de Node.js.
     Pour plus de détails sur cette option du compilateur, voir [TypeScript - Module Resolution](https://www.typescriptlang.org/tsconfig/#moduleResolution).

   * **`target: "es2022"`** *(Recommandé)* — Génère un code JavaScript moderne compatible avec les versions récentes de Node.js.
     Pour plus de détails sur cette option du compilateur, voir [TypeScript - Target](https://www.typescriptlang.org/tsconfig/#target).

   * **`rootDir: "."`** — Traite le répertoire qui contient `tsconfig.json` comme la racine de vos fichiers d’entrée. TypeScript l’utilise avec `outDir` pour reproduire la structure de votre dossier source dans le dossier de sortie.
     Pour plus de détails sur cette option du compilateur, voir [TypeScript - Root Dir](https://www.typescriptlang.org/tsconfig/#rootDir).

   * **`outDir: "dist"`** — Écrit le code JavaScript généré (et les autres sorties du compilateur) dans le dossier `dist`.
     Pour plus de détails sur cette option du compilateur, voir [TypeScript - Out Dir](https://www.typescriptlang.org/tsconfig/#outDir).

3. Installez Weave et toute autre bibliothèque requise :

   ```bash theme={null}
   npm install weave
   ```

4. Compilez votre fichier TypeScript.

   Pour un fichier d’exemple `test.ts` :

   ```bash theme={null}
   npx tsc
   ```

   Cette commande compile le fichier en `dist/test.js`.

5. Exécutez le fichier compilé avec Node.js et préchargez l’instrumentation Weave :

   ```bash theme={null}
   node --import=weave/instrument dist/test.js
   ```

L’option `--import` garantit que le module `weave/instrument` est chargé avant les autres modules afin que Weave puisse automatiquement instrumenter les bibliothèques et intégrations prises en charge.

Weave doit être installé localement dans le projet que vous exécutez.

Votre projet ESM est maintenant configuré pour que Weave précharge son instrumentation avant les autres modules et trace automatiquement les appels aux bibliothèques prises en charge.

<div id="advanced-usage-and-troubleshooting">
  ## Utilisation avancée et dépannage
</div>

Les sections suivantes couvrent les cas limites et les solutions de contournement lorsque le patching automatique du SDK TypeScript ne fonctionne pas comme prévu. Par exemple, des environnements ESM uniquement, des configurations de bundler comme Next.js ou des environnements d’exécution contraints peuvent entraîner des problèmes. Si vous constatez des traces manquantes ou des problèmes d’intégration, commencez ici.

<div id="use-node_options-only-for-esm">
  ### Utiliser `NODE_OPTIONS` (uniquement pour ESM)
</div>

<Warning>
  Utilisez `NODE_OPTIONS` avec prudence, car cela s’applique à tous les processus Node.js de l’environnement et peut entraîner des effets de bord.
</Warning>

Si vous utilisez un projet ESM et que vous ne pouvez pas passer d’options CLI (par exemple, en raison de contraintes liées aux outils CLI ou aux frameworks), définissez la variable d’environnement `NODE_OPTIONS` :

```bash theme={null}
export NODE_OPTIONS="--import=weave/instrument"
```

<div id="bundler-compatibility">
  ### Compatibilité des bundlers
</div>

Certains frameworks et bundlers, comme Next.js, peuvent intégrer des bibliothèques tierces au bundle d’une manière qui empêche Node.js d’effectuer leur patching à l’exécution.

Si cela correspond à votre configuration, essayez les étapes suivantes :

1. Marquez les bibliothèques LLM comme externes dans la configuration de votre bundler. Cela évite que le bundler les intègre au bundle, afin que Weave puisse effectuer correctement leur patching à l’exécution.

   L’exemple suivant montre comment marquer le package `openai` comme externe dans une configuration `next.config.js`, ce qui évite que le bundler l’intègre au bundle. Le module se charge à l’exécution, ce qui permet à Weave d’effectuer automatiquement son patching et de le suivre. Utilisez cette configuration lorsque vous travaillez avec des frameworks comme Next.js pour activer l’instrumentation automatique.

   ```js theme={null}
   externals: {
   'openai': 'commonjs openai'
   }
   ```

2. Si le patching échoue toujours, utilisez l’[instrumentation manuelle](#manual-patching-fallback-option).

<div id="manual-patching-fallback-option">
  ### Patching manuel (option de repli)
</div>

<Warning>
  Le patching manuel est l’approche historique. Utilisez-le uniquement lorsque le patching automatique ne fonctionne pas.
</Warning>

Parfois, vous devrez peut-être encore utiliser l’instrumentation manuelle :

```ts twoslash lines theme={null}
// @noErrors
import { wrapOpenAI } from 'weave';
const client = wrapOpenAI(new OpenAI());
```