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

# TypeScript SDK: 서드파티 인테그레이션 가이드

> Weave TypeScript SDK와 서드파티 라이브러리 통합하기

이 가이드는 Weave TypeScript SDK와 서드파티 라이브러리(예: OpenAI)를 통합하는 방법을 설명합니다. 애플리케이션에서 지원되는 라이브러리에 대한 Call을 Weave가 자동으로 트레이스하도록 하려는 TypeScript 개발자를 대상으로 합니다.

Weave는 자동 계측을 지원하므로 설정을 간소화하고 수동 설정의 필요성을 줄여줍니다.

<Warning>
  **변경 사항은 무엇인가요?**
  [PR #4554](https://github.com/wandb/weave/pull/4554)부터 Weave는 로드 시 OpenAI와 같은 지원되는 라이브러리를 자동으로 패치합니다. 더 이상 수동으로 래핑할 필요가 없습니다:

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

  대부분의 경우 Weave가 자동으로 처리합니다. 그러나 [고급 사용법](#advanced-usage)에서 예외가 발생할 수 있습니다.
</Warning>

<h2 id="use-weave-integrations-with-your-typescript-project">
  Weave 인테그레이션을 TypeScript 프로젝트에서 사용하는 방법
</h2>

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

<h3 id="if-youre-unsure-which-type-of-project-you-have">
  어떤 유형의 프로젝트인지 확신이 서지 않는 경우
</h3>

TypeScript 파일을 도구를 사용해 직접 run하는 경우:

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

사용 중인 환경에 따라 모듈 시스템이 암시적으로 결정될 수 있습니다. 일관된 동작을 위해 `package.json` 및 `tsconfig.json` 파일을 명시적으로 정의하세요.

프로젝트가 CommonJS 또는 ESM을 사용하는지 확인하려면 `package.json`의 `type` 필드를 확인하세요:

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

* `type`이 `"module"`인 경우, 프로젝트는 ESM을 사용합니다.
* `type` 필드가 없거나 `"commonjs"`로 설정된 경우, 프로젝트는 기본적으로 CommonJS를 사용합니다.

<h3 id="set-up-a-commonjs-project">
  CommonJS 프로젝트 설정
</h3>

CommonJS 프로젝트의 경우 추가 설정 없이 자동 계측이 작동합니다.

CommonJS를 위해 프로젝트를 설정하려면:

1. `package.json`을 생성하거나 업데이트하세요:

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

2. CommonJS와 호환되는 설정으로 `tsconfig.json`을 생성하세요:

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

4. TypeScript 파일을 컴파일하세요.

   예시 파일 `test.ts`의 경우:

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

   이 명령은 파일을 `dist/test.js`로 컴파일합니다.

5. 컴파일된 파일을 Node.js로 실행하세요:

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

이제 CommonJS 프로젝트가 구성되어 코드가 실행될 때 Weave가 지원되는 라이브러리를 자동으로 계측합니다. CommonJS는 Node.js `require` 모듈 로더를 사용하므로 ESM 프로젝트에서 사용하는 `--import` 플래그 없이도 Weave가 지원되는 라이브러리를 자동으로 계측할 수 있습니다.

<h3 id="set-up-an-esm-project">
  ESM 프로젝트 설정
</h3>

ESM TypeScript 프로젝트에서 Weave를 사용하려면 Node.js ESM에 맞게 프로젝트를 설정하고, 코드를 컴파일한 다음, `--import` 플래그를 사용해 Node.js를 시작하세요. 이렇게 하면 다른 모듈이 로드되기 전에 Weave가 계측을 등록할 수 있습니다.

ESM용으로 프로젝트를 설정하려면 다음 단계를 따르세요.

1. `package.json`을 생성하거나 업데이트하세요.

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

2. Node와 호환되는 ESM 설정으로 `tsconfig.json`을 생성하세요.

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

4. TypeScript 파일을 컴파일하세요.

   예시 파일 `test.ts`의 경우:

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

   이 명령은 파일을 `dist/test.js`로 컴파일합니다.

5. Weave 계측을 미리 로드하면서 Node.js로 컴파일된 파일을 실행하세요.

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

`--import` 플래그를 사용하면 `weave/instrument` 모듈이 다른 모듈보다 먼저 로드되므로, Weave가 지원되는 라이브러리와 인테그레이션을 자동으로 계측할 수 있습니다.

Weave는 실행하는 프로젝트에 로컬로 설치되어 있어야 합니다.

이제 ESM 프로젝트 설정이 완료되었습니다. Weave가 다른 모듈보다 먼저 계측을 로드하고, 지원되는 라이브러리에 대한 Call을 자동으로 트레이스합니다.

<h2 id="advanced-usage-and-troubleshooting">
  고급 사용법 및 문제 해결
</h2>

다음 섹션에서는 TypeScript SDK의 자동 패치가 예상대로 동작하지 않는 예외 상황과 그 해결 방법을 다룹니다. 예를 들어 ESM 전용 환경, Next.js 같은 번들러 설정, 제약이 있는 런타임 환경에서는 문제가 발생할 수 있습니다. 트레이스가 누락되거나 인테그레이션 문제가 발생하면 이 섹션부터 확인하세요.

<h3 id="use-node_options-only-for-esm">
  `NODE_OPTIONS` 사용 (ESM 전용)
</h3>

<Warning>
  `NODE_OPTIONS`는 환경의 모든 Node.js 프로세스에 영향을 미치고 부작용을 일으킬 수 있으므로 주의해서 사용하세요.
</Warning>

ESM 프로젝트를 사용 중이고 CLI 플래그를 전달할 수 없는 경우(예: CLI 도구 또는 프레임워크의 제약으로 인해), `NODE_OPTIONS` 환경 변수를 설정하세요:

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

<h3 id="bundler-compatibility">
  번들러 호환성
</h3>

Next.js 같은 일부 프레임워크와 번들러는 서드파티 라이브러리를 번들링하는 방식 때문에 Node.js가 런타임에 해당 라이브러리를 패치하지 못할 수 있습니다.

이 경우에 해당한다면 다음 단계를 따라 해 보세요.

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

   다음 예시는 `next.config.js` 설정에서 `openai` 패키지를 external로 지정해 번들러가 이를 번들링하지 않도록 하는 방법을 보여 줍니다. 모듈이 런타임에 로드되므로 Weave가 자동으로 패치하고 추적할 수 있습니다. Next.js 같은 프레임워크에서 자동 계측을 사용하려면 이 설정을 적용하세요.

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

2. 그래도 패치에 실패하면 [수동 계측](#manual-patching-fallback-option)을 사용하세요.

<h3 id="manual-patching-fallback-option">
  수동 패치 (대체 옵션)
</h3>

<Warning>
  수동 패치는 레거시 접근 방식입니다. 자동 패치가 작동하지 않을 때만 사용하세요.
</Warning>

때때로 수동 계측을 사용해야 할 수도 있습니다:

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