Skip to main content
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.

​
Usage instructions

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

​
CommonJS

For CommonJS projects, no special configuration is required. Automatic patching works out of the box. Install Weave: 
npm install weave

​
ESM

For ESM projects, use the Node.js --import CLI flag to enable auto-instrumentation. The weave/instrument module is available as long as the weave package is installed.
  1. Install Weave: 
    npm install weave
  2. Compile your TypeScript file. For an example file test.ts, compile it with: 
    npx tsc
    This assumes your tsconfig.json outputs compiled files to a dist directory, for example: 
    {
  "compilerOptions": {
    "rootDir": ".",
    "outDir": "dist"
  }
}
    After compiling, your file will be available as dist/test.js.
  3. Run the compiled file with the Node.js --import=weave/instrument flag: 
    node --import=weave/instrument dist/test.js
Weave must be installed locally in the project you’re running. Because ESM loads modules differently than CommonJS, Weave must be loaded before other modules to enable automatic instrumentation. Using the import flag ensures Weave is loaded before other modules so it can patch them.

​
If you’re unsure which type of project you have

If you are running a TypeScript file directly with a tool like: 
npx tsx test.ts
your project may still be using ESM depending on your package.json configuration. To determine if you are using CommonJS or ESM, open your package.json and check the type field: 
"type": "module"
If type is module then your project uses ESM. If type is commonjs or is missing, then your project uses CommonJS.

​
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 and should only be used 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());