README.md

Braintrust JavaScript SDK

An isomorphic JavaScript/TypeScript SDK for logging, tracing, and evaluating AI applications with Braintrust. For more details, see the Braintrust docs

Installation

Install the SDK:

npm install braintrust

Quickstart

Run a simple experiment (replace YOUR_API_KEY with your Braintrust API key):

import * as braintrust from "braintrust";

async function main() {
  const experiment = await braintrust.init("NodeTest", {
    apiKey: "YOUR_API_KEY",
  });

  experiment.log({
    input: { test: 1 },
    output: "foo",
    expected: "bar",
    scores: {
      n: 0.5,
    },
    metadata: {
      id: 1,
    },
  });

  console.log(await experiment.summarize());
}

main().catch(console.error);

Auto-Instrumentation

Braintrust can automatically instrument popular AI SDKs (OpenAI, Anthropic, Vercel AI SDK, and others) to log calls without manual wrapper code.

Node.js

Use the runtime import hook:

node --import braintrust/hook.mjs app.js

Bundled Apps

Use a bundler plugin:

Vite:

import { vitePlugin } from "braintrust/vite";

export default {
  plugins: [vitePlugin()],
};

Webpack:

const { webpackPlugin } = require("braintrust/webpack");

module.exports = {
  plugins: [webpackPlugin()],
};

esbuild:

import { esbuildPlugin } from "braintrust/esbuild";

await esbuild.build({
  plugins: [esbuildPlugin()],
});

Rollup:

import { rollupPlugin } from "braintrust/rollup";

export default {
  plugins: [rollupPlugin()],
};

If you use TypeScript or other transpilation plugins, place the Braintrust plugin after them so transformed output is instrumented.

For deeper details, see the auto-instrumentation architecture docs.

Browser Support

For browser-only applications, use the dedicated browser package:

npm install @braintrust/browser braintrust

See the @braintrust/browser README for details and current limitations.

Migration Guides

Upgrading from 2.x to 3.x

See the Migrate from v2.x to v3.x guide.

In 3.x, browser usage should move to @braintrust/browser instead of relying on the legacy braintrust/browser path.

Upgrading from 1.x to 2.x

See the Migrate from v1.x to v2.x guide.

Upgrading from 0.x to 1.x

See the Migrate from v1.x to v2.x guide.