TypeScript SDK: Third-Party Integration Guide

Integrate third-party libraries with the Weave TypeScript SDK

This guide describes how to integrate third-party libraries (e.g., OpenAI) with the Weave TypeScript SDK. Weave supports automatic instrumentation, making setup easier and reducing the need for manual configuration.

What changed? As of PR #4554, supported libraries such as OpenAI are automatically patched when Weave is loaded. You no longer need to manually wrap them, as was the case previously:

weave.wrapOpenAI(new OpenAI());

Weave will generally handle this automatically. However, there may be edge cases.

Use Weave integrations with your TypeScript project

TypeScript projects can use either the CommonJS or ESM module system.

If you’re unsure which type of project you have

If you run a TypeScript file directly with a tool such as:

npx tsx test.ts

the module system may be determined implicitly by your environment. For consistent behavior, we recommend explicitly defining package.json and tsconfig.json files.

To determine whether a project uses CommonJS or ESM, check the type field in package.json:

"type": "module"

• If type is "module", the project uses ESM.
• If the type field is missing or set to "commonjs", the project defaults to using CommonJS.

Set up a CommonJS project

For CommonJS projects, automatic instrumentation works without additional configuration.

To configure your project for CommonJS:

1. Create or update your package.json:

   {
     "type": "commonjs"
   }
   

2. Create a tsconfig.json with CommonJS-compatible settings:

   {
     "compilerOptions": {
       "module": "CommonJS",
       "target": "es2022",
       "rootDir": ".",
       "outDir": "dist"
     }
   }
   

   These settings configure TypeScript to compile for CommonJS:

   • module: "CommonJS" — Compiles modules to CommonJS format (require/module.exports). For details on this compiler option, see TypeScript - Module.

   • target: "es2022" (Recommended) — Emits modern JavaScript compatible with recent Node.js versions. For details on this compiler option, see TypeScript - Target.

   • rootDir: "." — Treats the directory that contains tsconfig.json as the root of your input files. TypeScript uses this with outDir to mirror your source folder layout in the output. For details on this compiler option, see TypeScript - Root Dir.

   • outDir: "dist" — Writes emitted JavaScript (and other compiler outputs) into the dist folder. For details on this compiler option, see TypeScript - Out Dir.

3. Install Weave and any other required libraries:

   npm install weave
   

4. Compile your TypeScript file.

   For an example file test.ts:

   npx tsc
   

   This compiles the file to dist/test.js.

5. Run the compiled file with Node.js:

   node dist/test.js
   

Because CommonJS uses Node.js’s require module loader, Weave can automatically instrument supported libraries without requiring the --import flag used in ESM projects.

Set up an ESM project

To use Weave with an ESM TypeScript project, configure your project for Node.js ESM, compile your code, and start Node.js with the --import flag so Weave can register its instrumentation before other modules load.

To configure your project for ESM:

1. Create or update your package.json:

   {
     "type": "module"
   }
   

2. Create a tsconfig.json with Node-compatible ESM settings:

   {
     "compilerOptions": {
       "module": "nodenext",
       "moduleResolution": "nodenext",
       "target": "es2022",
       "rootDir": ".",
       "outDir": "dist"
     }
   }
   

   These settings configure TypeScript to compile for modern Node.js ESM:

   • module: "nodenext" — Compiles modules using Node.js ESM semantics.
     For details on this compiler option, see TypeScript - Module.

   • moduleResolution: "nodenext" — Ensures module resolution follows Node.js ESM rules.
     For details on this compiler option, see TypeScript - Module Resolution.

   • target: "es2022" (Recommended) — Emits modern JavaScript compatible with recent Node.js versions.
     For details on this compiler option, see TypeScript - Target.

   • rootDir: "." — Treats the directory that contains tsconfig.json as the root of your input files. TypeScript uses this with outDir to mirror your source folder layout in the output.
     For details on this compiler option, see TypeScript - Root Dir.

   • outDir: "dist" — Writes emitted JavaScript (and other compiler outputs) into the dist folder.
     For details on this compiler option, see TypeScript - Out Dir.

3. Install Weave and any other required libraries:

   npm install weave
   

4. Compile your TypeScript file.

   For an example file test.ts:

   npx tsc
   

   This compiles the file to dist/test.js.

5. Run the compiled file with Node.js and preload the Weave instrumentation:

   node --import=weave/instrument dist/test.js
   

The --import flag ensures the weave/instrument module loads before other modules so Weave can automatically instrument supported libraries and integrations.

Weave must be installed locally in the project you run.

Advanced usage and troubleshooting

This section covers edge cases and workarounds for when the TypeScript SDK’s automatic patching doesn’t work as expected. For example, ESM-only environments, bundler setups like Next.js, or constrained runtime environments may cause unexpected issues. If you’re seeing missing traces or integration issues, start here.

Use NODE_OPTIONS (only for ESM)

Use with NODE_OPTIONS with caution, as this affects all Node.js processes in the environment and may introduce side effects.

If you’re using an ESM project and cannot pass CLI flags (e.g., due to constraints in CLI tools or frameworks), set the NODE_OPTIONS environment variable:

export NODE_OPTIONS="--import=weave/instrument"

Bundler compatibility

Some frameworks and bundlers, such as Next.js, may bundle third-party libraries in ways that prevent Node.js from patching them at runtime.

If this describes your setup, try the following steps:

1. Mark LLM libraries as external in your bundler configuration. This prevents them from being bundled, so Weave can patch them correctly at runtime.

   The following example shows how to mark the openai package as external in a next.config.js configuration, which prevents it from being bundled. The module is loaded at runtime, so Weave can automatically patch and track it. Use this setup when working with frameworks like Next.js to enable auto-instrumentation.

   externals: {
   'openai': 'commonjs openai'
   }
   

2. If patching still fails, fall back to manual instrumentation.

Manual patching (fallback option)

Manual patching is the legacy approach. Only use it when auto-patching doesn’t work.

In some cases, you may still need to use manual instrumentation:

import { wrapOpenAI } from 'weave';
const client = wrapOpenAI(new OpenAI());