> ## 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 프로젝트에서 Weave 인테그레이션 사용하기
</div>

다음 섹션에서는 프로젝트에서 사용하는 모듈 시스템을 파악하는 방법과, Weave가 지원되는 서드파티 라이브러리를 자동으로 계측할 수 있도록 프로젝트를 설정하는 방법을 설명합니다. TypeScript 프로젝트는 CommonJS 또는 ESM 모듈 시스템을 사용할 수 있으며, 필요한 설정은 두 경우에 따라 약간 다릅니다.

<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`과 함께 사용해 출력에서 소스 폴더 레이아웃을 그대로 반영합니다.
     이 컴파일러 옵션에 대한 자세한 내용은 [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에 맞게 구성하고, 코드를 컴파일한 다음, 다른 모듈이 로드되기 전에 Weave가 계측을 등록할 수 있도록 `--import` 플래그와 함께 Node.js를 시작하세요.

프로젝트를 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`와 함께 사용해 출력 시 소스 폴더 레이아웃을 그대로 반영합니다.
     이 컴파일러 옵션에 대한 자세한 내용은 [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가 런타임에 패치할 수 없도록 서드파티 라이브러리를 번들링할 수 있습니다.

현재 설정이 이에 해당한다면, 다음 step을 사용해 보세요:

1. 번들러 설정에서 LLM 라이브러리를 external로 지정합니다. 이렇게 하면 번들러가 해당 라이브러리를 번들링하지 않으므로 Weave가 런타임에 올바르게 패치할 수 있습니다.

   다음 예시는 `next.config.js` 설정에서 `openai` 패키지를 external로 지정하는 방법을 보여 줍니다. 이렇게 하면 번들러가 해당 패키지를 번들링하지 않습니다. 모듈은 런타임에 로드되므로 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());
```