> ## 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.

# TypeScript SDK: サードパーティインテグレーションガイド

> サードパーティライブラリを Weave TypeScript SDK に統合する

このガイドでは、サードパーティライブラリ (例: OpenAI) を Weave TypeScript SDK に統合する方法を説明します。これは、アプリケーション内でサポートされるライブラリへの Call を Weave に自動的にトレースさせたい TypeScript 開発者を対象としています。

Weave は自動インストルメンテーションをサポートしているため、セットアップが簡単になり、手動設定の必要性も減ります。

<Warning>
  **何が変わりましたか？**
  [PR #4554](https://github.com/wandb/weave/pull/4554) 以降、Weave は読み込み時に OpenAI などのサポートされるライブラリを自動的にパッチします。以前のように手動でラップする必要はありません。

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

  ほとんどの場合、これは Weave が自動的に処理します。ただし、[エッジケース](#advanced-usage) が発生する場合があります。
</Warning>

<div id="use-weave-integrations-with-your-typescript-project">
  ## TypeScript project で Weave インテグレーションを使用する
</div>

以下のセクションでは、お使いの project がどのモジュールシステムを使用しているかを確認し、Weave がサポートされるサードパーティライブラリを自動的にインストルメントできるようにその project を設定する方法を説明します。TypeScript project では、CommonJS または ESM のいずれかのモジュールシステムを使用でき、必要な設定はこの 2 つで若干異なります。

<div id="if-youre-unsure-which-type-of-project-you-have">
  ### どのタイプのプロジェクトかわからない場合
</div>

次のようなツールでTypeScriptファイルを直接実行している場合:

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

モジュールシステムは、環境に応じて暗黙的に決まる場合があります。動作を一貫させるため、`package.json` と `tsconfig.json` を明示的に定義してください。

プロジェクトで CommonJS と ESM のどちらを使用しているかを判断するには、`package.json` の `type` フィールドを確認します。

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

* `type` が `"module"` の場合、プロジェクトでは ESM が使用されます。
* `type` フィールドが存在しないか、`"commonjs"` に設定されている場合、プロジェクトではデフォルトで CommonJS が使用されます。

<div id="set-up-a-commonjs-project">
  ### CommonJS プロジェクトを設定する
</div>

CommonJS プロジェクトでは、自動インストルメンテーションは追加の設定なしで動作します。

プロジェクトを CommonJS 用に設定するには、次の手順に従います。

1. `package.json` を作成または更新します。

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

2. CommonJS と互換性のある設定で `tsconfig.json` を作成します。

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

   これらの設定により、TypeScript は CommonJS 向けにコンパイルされます。

   * **`module: "CommonJS"`** — モジュールを CommonJS 形式 (`require`/`module.exports`) にコンパイルします。
     このコンパイラオプションの詳細については、[TypeScript - Module](https://www.typescriptlang.org/tsconfig/#module) を参照してください。

   * **`target: "es2022"`** *(推奨)* — 最近の Node.js バージョンと互換性のあるモダンな JavaScript を出力します。
     このコンパイラオプションの詳細については、[TypeScript - Target](https://www.typescriptlang.org/tsconfig/#target) を参照してください。

   * **`rootDir: "."`** — `tsconfig.json` を含むディレクトリを入力ファイルのルートとして扱います。TypeScript はこれを `outDir` と組み合わせて使用し、出力先でソースフォルダーの Layout を反映します。
     このコンパイラオプションの詳細については、[TypeScript - Root Dir](https://www.typescriptlang.org/tsconfig/#rootDir) を参照してください。

   * **`outDir: "dist"`** — 生成された JavaScript (およびその他のコンパイラ出力) を `dist` フォルダーに書き込みます。
     このコンパイラオプションの詳細については、[TypeScript - Out Dir](https://www.typescriptlang.org/tsconfig/#outDir) を参照してください。

3. Weave と、必要なその他のライブラリをインストールします。

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

4. TypeScript ファイルをコンパイルします。

   たとえば `test.ts` というファイルの場合は、次を実行します。

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

   これにより、ファイルは `dist/test.js` にコンパイルされます。

5. コンパイルしたファイルを Node.js で実行します。

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

これで CommonJS プロジェクトの設定は完了し、コードの実行時に Weave がサポートされるライブラリを自動的にインストルメントします。CommonJS は Node.js の `require` モジュールローダーを使用するため、Weave は ESM プロジェクトで使用される `--import` フラグなしで、サポートされるライブラリを自動的にインストルメントできます。

<div id="set-up-an-esm-project">
  ### ESM プロジェクトを設定する
</div>

ESM TypeScript プロジェクトで Weave を使用するには、プロジェクトを Node.js ESM 用に設定し、コードをコンパイルしたうえで、`--import` フラグ付きで Node.js を起動します。これにより、他のモジュールが読み込まれる前に Weave がインストルメントを登録できます。

プロジェクトを ESM 向けに設定するには、次の手順に従います。

1. `package.json` を作成または更新します。

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

2. Node.js 互換の ESM 設定を含む `tsconfig.json` を作成します。

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

   これらの設定により、TypeScript はモダンな Node.js ESM 向けにコンパイルされます。

   * **`module: "nodenext"`** — Node.js ESM のセマンティクスを使用してモジュールをコンパイルします。
     このコンパイラオプションの詳細は、[TypeScript - Module](https://www.typescriptlang.org/tsconfig/#module) を参照してください。

   * **`moduleResolution: "nodenext"`** — モジュール解決が Node.js ESM のルールに従うようにします。
     このコンパイラオプションの詳細は、[TypeScript - Module Resolution](https://www.typescriptlang.org/tsconfig/#moduleResolution) を参照してください。

   * **`target: "es2022"`** *(推奨)* — 新しい Node.js バージョンと互換性のあるモダンな JavaScript を出力します。
     このコンパイラオプションの詳細は、[TypeScript - Target](https://www.typescriptlang.org/tsconfig/#target) を参照してください。

   * **`rootDir: "."`** — `tsconfig.json` を含むディレクトリを入力ファイルのルートとして扱います。TypeScript はこれを `outDir` と組み合わせて使用し、出力先でもソースフォルダの Layout を反映します。
     このコンパイラオプションの詳細は、[TypeScript - Root Dir](https://www.typescriptlang.org/tsconfig/#rootDir) を参照してください。

   * **`outDir: "dist"`** — 出力された JavaScript (およびその他のコンパイラ出力) を `dist` フォルダに書き込みます。
     このコンパイラオプションの詳細は、[TypeScript - Out Dir](https://www.typescriptlang.org/tsconfig/#outDir) を参照してください。

3. Weave と必要なライブラリをインストールします。

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

4. TypeScript ファイルをコンパイルします。

   たとえば `test.ts` というファイルの場合は、次のように実行します。

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

   これにより、ファイルは `dist/test.js` にコンパイルされます。

5. Node.js でコンパイル済みファイルを実行し、Weave のインストルメントを事前に読み込みます。

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

`--import` フラグにより、`weave/instrument` モジュールが他のモジュールより先に読み込まれるため、Weave はサポートされるライブラリやインテグレーションに自動でインストルメントを適用できます。

Weave は、実行するプロジェクトにローカルインストールされている必要があります。

これで ESM プロジェクトは、他のモジュールより前に Weave のインストルメントが事前に読み込まれ、サポートされるライブラリへの Call が自動的にトレースされるように設定されました。

<div id="advanced-usage-and-troubleshooting">
  ## 高度な使い方とトラブルシューティング
</div>

以下のセクションでは、TypeScript SDK の自動パッチ適用が期待どおりに動作しない場合のエッジケースと回避策を説明します。たとえば、ESM 専用の環境、Next.js などのバンドラー構成、または制約のあるランタイム環境では、問題が発生することがあります。トレースが欠落している場合やインテグレーションに問題がある場合は、まずこのセクションを確認してください。

<div id="use-node_options-only-for-esm">
  ### `NODE_OPTIONS` を使用する (ESM の場合のみ)
</div>

<Warning>
  `NODE_OPTIONS` の使用には注意してください。環境内のすべての Node.js プロセスに影響し、意図しない副作用を招く可能性があります。
</Warning>

ESM のプロジェクトを使用していて、CLI フラグを渡せない場合 (たとえば、CLI ツールやフレームワークの制約がある場合) は、`NODE_OPTIONS` 環境変数を設定してください：

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

<div id="bundler-compatibility">
  ### バンドラーの互換性
</div>

Next.js などの一部のフレームワークやバンドラーでは、Node.js が実行時にパッチを適用できない形でサードパーティライブラリがバンドルされることがあります。

これが現在の設定に当てはまる場合は、次の手順を試してください。

1. バンドラーの設定で、LLM ライブラリを外部として指定します。これによりそれらはバンドルされなくなるため、Weave が実行時に正しくパッチを適用できるようになります。

   次の例は、`next.config.js` の設定で `openai` パッケージを外部として指定する方法を示しています。これにより、バンドラーはそれをバンドルしません。モジュールは実行時に読み込まれるため、Weave が自動的にパッチを適用してトラッキングできます。Next.js のようなフレームワークで作業する場合は、自動インストルメンテーションを有効にするためにこの設定を使用してください。

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

2. それでもパッチの適用に失敗する場合は、[手動インストルメンテーション](#manual-patching-fallback-option) に切り替えてください。

<div id="manual-patching-fallback-option">
  ### 手動パッチ適用 (フォールバックオプション)
</div>

<Warning>
  手動パッチ適用は従来の方法です。自動パッチ適用が機能しない場合にのみ使用してください。
</Warning>

状況によっては、引き続き手動インストルメンテーションを使用する必要がある場合があります：

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