> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from v2.x to v3.x

> Guide for migrating from TypeScript SDK v2.x to v3.x

## What's changed

v3.0.0 introduces two main changes:

**Nunjucks templating is now a separate package.** If you use `templateFormat: "nunjucks"` with prompts, you must install `@braintrust/templates-nunjucks-js` and register the plugin at startup. Mustache templating continues to work without any changes.

**Improved support for restricted environments.** The SDK now provides dedicated builds for Node.js, browsers, edge runtimes (such as Cloudflare Workers and Next.js Edge), and workerd. Bundlers automatically choose the correct build for your target environment, so most users won’t need to make any changes.

## Migration steps

<Steps>
  <Step title="Upgrade the SDK">
    <CodeGroup>
      ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      npm install braintrust@latest
      ```

      ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      pnpm add braintrust@latest
      ```

      ```bash yarn theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      yarn add braintrust@latest
      ```
    </CodeGroup>
  </Step>

  <Step title="Install the Nunjucks plugin (if applicable)">
    If you use `templateFormat: "nunjucks"`, install the plugin package:

    <CodeGroup>
      ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      npm install @braintrust/templates-nunjucks-js
      ```

      ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      pnpm add @braintrust/templates-nunjucks-js
      ```

      ```bash yarn theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      yarn add @braintrust/templates-nunjucks-js
      ```
    </CodeGroup>

    If you only use Mustache templates or no templating at all, skip this step.
  </Step>

  <Step title="Register the Nunjucks plugin (if applicable)">
    At the entry point of your application, import and register the plugin before using any Braintrust prompts:

    ```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    import { registerTemplatePlugin } from "braintrust";
    import { nunjucksPlugin } from "@braintrust/templates-nunjucks-js";

    registerTemplatePlugin(nunjucksPlugin);
    ```

    This only needs to be called once. After that, `templateFormat: "nunjucks"` works as before.
  </Step>
</Steps>

## Troubleshooting

**"Nunjucks templating requires @braintrust/templates-nunjucks"** — You are using `templateFormat: "nunjucks"` but haven't installed or registered the plugin. Follow steps 2 and 3 above.

**Type errors after upgrading** — If you reference `TemplateRendererPlugin` in your own code, it is exported directly from `braintrust`:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { type TemplateRendererPlugin } from "braintrust";
```

<Note>
  If you encounter issues during migration, please [open an issue](https://github.com/braintrustdata/braintrust-sdk-javascript/issues) with details about your setup.
</Note>