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

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

> Intégrer 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 limite les réglages manuels.

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

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

  Dans la plupart des cas, Weave s’en charge automatiquement. Certains [cas limites](#advanced-usage) peuvent toutefois se présenter.
</Warning>

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

Les sections suivantes expliquent comment identifier le système de modules utilisé par votre projet, puis comment 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 de l’un à l’autre.

<h3 id="if-youre-unsure-which-type-of-project-you-have">
  Si vous ne savez pas de quel type de projet il s’agit
</h3>

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

```bash theme={"system"}
npx tsx test.ts
```

votre environnement peut déterminer implicitement le système de modules. 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, consultez le champ `type` du fichier `package.json` :

```json theme={"system"}
"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.

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

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

Pour configurer votre projet pour CommonJS :

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

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

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

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

   Ces paramètres configurent TypeScript pour compiler vers CommonJS :

   * `module: "CommonJS"`. Compile les modules au format CommonJS (`require` ou `module.exports`).
     Pour plus de détails sur cette option du compilateur, consultez [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, consultez [TypeScript - Target](https://www.typescriptlang.org/tsconfig/#target).

   * `rootDir: "."`. Définit le répertoire contenant `tsconfig.json` comme racine de vos fichiers d’entrée. TypeScript s’en sert, avec `outDir`, pour reproduire l’arborescence de votre dossier source dans la sortie.
     Pour plus de détails sur cette option du compilateur, consultez [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, consultez [TypeScript - Out Dir](https://www.typescriptlang.org/tsconfig/#outDir).

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

   ```bash theme={"system"}
   npm install weave
   ```

4. Compilez votre fichier TypeScript.

   Par exemple, pour un fichier `test.ts` :

   ```bash theme={"system"}
   npx tsc
   ```

   Cette commande génère le fichier compilé `dist/test.js`.

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

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

Votre projet CommonJS est désormais configuré pour que Weave instrumente automatiquement les bibliothèques prises en charge à l’exécution de votre code. Comme CommonJS s’appuie sur le chargeur de modules `require` de Node.js, Weave peut instrumenter automatiquement ces bibliothèques sans l’option `--import` nécessaire dans les projets ESM.

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

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

Pour configurer votre projet pour l’ESM :

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

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

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

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

   Ces paramètres configurent TypeScript pour compiler vers l’ESM moderne de Node.js :

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

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

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

   * `rootDir: "."`. Définit le répertoire contenant `tsconfig.json` comme racine de vos fichiers d’entrée. TypeScript s’en sert avec `outDir` pour reproduire l’arborescence de vos dossiers sources dans la sortie.
     Pour en savoir plus sur cette option du compilateur, consultez [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 en savoir plus sur cette option du compilateur, consultez [TypeScript - Out Dir](https://www.typescriptlang.org/tsconfig/#outDir).

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

   ```bash theme={"system"}
   npm install weave
   ```

4. Compilez votre fichier TypeScript.

   Par exemple, pour un fichier `test.ts` :

   ```bash theme={"system"}
   npx tsc
   ```

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

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

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

L’option `--import` garantit que le module `weave/instrument` est chargé avant les autres modules, ce qui permet à Weave d’instrumenter automatiquement 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 désormais configuré : Weave précharge son instrumentation avant les autres modules et trace automatiquement les appels aux bibliothèques prises en charge.

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

Les sections suivantes présentent les cas limites et les solutions de contournement à appliquer lorsque le patching automatique du SDK TypeScript ne fonctionne pas comme prévu. Des problèmes peuvent notamment survenir dans les environnements exclusivement ESM, avec des configurations de bundler comme Next.js ou dans des environnements d’exécution restreints. Si des traces sont manquantes ou si vous rencontrez des problèmes d’intégration, commencez par cette section.

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

<Warning>
  Utilisez `NODE_OPTIONS` avec prudence, car cette variable affecte tous les processus Node.js de l'environnement et peut provoquer des effets de bord.
</Warning>

Si vous utilisez un projet ESM et ne pouvez pas transmettre d'options en ligne de commande (par exemple, en raison de contraintes imposées par des outils CLI ou des frameworks), définissez la variable d'environnement `NODE_OPTIONS` :

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

<h3 id="bundler-compatibility">
  Compatibilité avec les bundlers
</h3>

Certains frameworks et bundlers, comme Next.js, peuvent empaqueter les bibliothèques tierces de telle sorte que Node.js ne puisse plus leur appliquer de patch au moment de l’exécution.

Si c’est le cas de votre configuration, essayez les étapes suivantes :

1. Déclarez les bibliothèques LLM comme externes dans la configuration de votre bundler. Le bundler ne les empaquette alors pas, et Weave peut leur appliquer correctement un patch au moment de l’exécution.

   L’exemple suivant montre comment déclarer le package `openai` comme externe dans une configuration `next.config.js`, afin que le bundler ne l’empaquette pas. Le module est chargé au moment de l’exécution, ce qui permet à Weave de lui appliquer automatiquement un patch et d’en assurer le suivi. Utilisez cette configuration avec des frameworks tels que Next.js pour activer l’instrumentation automatique.

   ```js theme={"system"}
   externals: {
   'openai': 'commonjs openai'
   }
   ```

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

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

<Warning>
  Le patching manuel est l'approche historique. Ne l'utilisez que si le patching automatique ne fonctionne pas.
</Warning>

Dans certains cas, vous devrez peut-être encore utiliser l’instrumentation manuelle :

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


## Related topics

- [Tracer votre code](/fr/products/wandb/weave/guides/tracking/create-call.md)