Skip to main content
skill CX Codex

upgrade-browser-sdk-v6 — Claude Code skill: what it does

upgrade-browser-sdk-v6 — a skill for Claude Code and Cursor migrating Datadog Browser SDK from version 5 to 6. Used during dependency upgrades or deprecated option cleanup.

MIT 134 installs ★ 185 updated 2026-10-22

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add datadog-labs/agent-skills --skill upgrade-browser-sdk-v6 -a claude-code
Open on GitHub

What upgrade-browser-sdk-v6 does

This skill automates the migration from version 5 to 6 of the Datadog client-side monitoring SDK. The agent steps through the codebase to replace outdated parameters such as useCrossSiteSessionCookie and sendLogsAfterSessionExpiration, update CDN paths, and adjust package.json dependencies. It also guides configuration changes for new default behaviors and verifies that bundlers support dynamic imports for lazy-loaded Session Replay.

The process accounts for dropped IE11 support and stricter TypeScript typing for the site option. The skill triggers when projects reference /v5/ CDN paths or request a monitoring upgrade.

What it helps with

  • update Datadog SDK version in package.json and CDN
  • remove deprecated v5 configuration options
  • adjust new default settings for RUM initialization
  • verify bundler support for Session Replay dynamic imports

Example prompts for the agent

  • Upgrade the Datadog Browser SDK to version 6 in this project
  • Find and replace v5 CDN paths with v6 in the codebase
  • Remove deprecated log options from the initialization config

How to install upgrade-browser-sdk-v6

1Skills CLI (Vercel)

npx skills add datadog-labs/agent-skills --skill upgrade-browser-sdk-v6 -a claude-code

2Manually: put the files in place

~/.claude/skills/upgrade-v6/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/upgrade-v6/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about upgrade-browser-sdk-v6

How to install upgrade-browser-sdk-v6 in Claude Code?

Run npx skills add datadog-labs/agent-skills --skill upgrade-browser-sdk-v6 -a claude-code followed by checking ~/.claude/skills/upgrade-v6/SKILL.md.

What does upgrade-browser-sdk-v6 do?

It performs a structured migration of Datadog Browser SDK from v5 to v6 by updating paths, dependencies, and configuration parameters.

What configuration updates does the skill check?

The agent reviews new default settings for user interactions, resource tracking, tracing context injection, and Session Replay loading.

Source text

SKILL.md · MIT
---
name: upgrade-browser-sdk-v6
description: >
  Upgrade Datadog Browser SDK from v5 to v6. Use when encountering removed options like
  useCrossSiteSessionCookie, sendLogsAfterSessionExpiration, or when dropping IE11 support,
  or when a project references datadoghq-browser-agent.com CDN with /v5/ paths.
metadata:
  version: "1.0.0"
  author: datadog-labs
  repository: https://github.com/datadog-labs/agent-skills
  tags: datadog,browser-sdk,rum,logs,migration,v6,upgrade
---

# Upgrade Datadog Browser SDK to v6

Systematic migration guide from v5 to v6. Follow steps 1-6 in order. Each step includes a search pattern to find affected code.

## Step 1: Update SDK version

**CDN setup** — update script `src` URLs:

| v5 pattern                                               | v6 replacement                                           |
| -------------------------------------------------------- | -------------------------------------------------------- |
| `datadoghq-browser-agent.com/us1/v5/datadog-rum.js`      | `datadoghq-browser-agent.com/us1/v6/datadog-rum.js`      |
| `datadoghq-browser-agent.com/us1/v5/datadog-logs.js`     | `datadoghq-browser-agent.com/us1/v6/datadog-logs.js`     |
| `datadoghq-browser-agent.com/us1/v5/datadog-rum-slim.js` | `datadoghq-browser-agent.com/us1/v6/datadog-rum-slim.js` |

Replace `us1` with your site: `eu1`, `us3`, `us5`, `ap1`, `ap2`. For US1-FED, the pattern is flat with no site prefix: `datadog-rum-v6.js`, `datadog-logs-v6.js`, `datadog-rum-slim-v6.js`.

Search: `grep -r "datadoghq-browser-agent.com.*v5" --include="*.html" --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx"`

**npm setup** — update `package.json` dependencies:

```
"@datadog/browser-rum": "^6.0.0"
"@datadog/browser-logs": "^6.0.0"
"@datadog/browser-rum-slim": "^6.0.0"
```

Then run your package manager (`npm install`, `yarn install`, etc.) and rebuild.

Also upgrade framework integrations to v6 if used: `@datadog/browser-rum-react`.

Search: `grep -r "@datadog/browser-" --include="package.json" .`

## Step 2: Remove deprecated options

### Removed from Core (affects both RUM and Logs)

| Option                      | Action                                               |
| --------------------------- | ---------------------------------------------------- |
| `useCrossSiteSessionCookie` | Replace with `usePartitionedCrossSiteSessionCookie`. |

### Removed from Logs

| Option                           | Action                                                                                                               |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `sendLogsAfterSessionExpiration` | Delete. In v6, logs are always sent after session expiration (without a session ID). The option is no longer needed. |

Search: `grep -rn 'useCrossSiteSessionCookie\|sendLogsAfterSessionExpiration' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"`

## Step 3: Update changed defaults

v6 changes several default behaviors. Review each and adjust if needed:

### 3a. `trackUserInteractions`, `trackResources`, and `trackLongTasks` default to `true`

In v5, these were `false` by default. In v6, they are enabled out of the box. This does not impact billing.

To preserve v5 behavior, explicitly disable **only the options that were not already enabled in v5**. If an option was already `true` in v5, leave it unchanged:

```js
DD_RUM.init({
  trackUserInteractions: false, // only if not already true in v5
  trackResources: false, // only if not already true in v5
  trackLongTasks: false, // only if not already true in v5
})
```

### 3b. `traceContextInjection` defaults to `"sampled"`

In v5, trace context was injected for all requests. In v6, it's only injected for sampled traces. If your `traceSampleRate` is 100% (the default), this has no impact.

To preserve v5 behavior:

```js
DD_RUM.init({
  traceContextInjection: 'all',
})
```

### 3c. `tracestate` header added with `tracecontext` propagator

The `tracecontext` propagator now sends an additional `tracestate` header. Your server must accept it. Add it to your existing `Access-Control-Allow-Headers` — do not replace the full list:

```
# Add tracestate alongside your existing headers
Access-Control-Allow-Headers: <existing-headers>, traceparent, tracestate
```

### 3d. `site` parameter is strongly typed

The `site` option has a stricter TypeScript type. If you pass a non-standard value, you get a type error. Use `proxy` for non-standard intake URLs instead.

Search: `grep -rn 'trackUserInteractions\|trackResources\|trackLongTasks\|traceContextInjection\|tracestate\|allowedTracingUrls\|propagatorTypes' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"`

Also search for all RUM init calls to catch projects that omit these options and relied on the v5 `false` defaults: `grep -rn 'DD_RUM\.init\|datadogRum\.init' --include="*.js" --include="*.ts" --include="*.tsx" --include="*.jsx" --include="*.html" --include="*.vue" --include="*.svelte"`. For each init call, check whether `trackUserInteractions`, `trackResources`, and `trackLongTasks` are explicitly set — if omitted, they now default to `true` in v6.

## Step 4: Handle Session Replay lazy loading

Session Replay is now lazy-loaded using dynamic imports. The module loads only for sessions sampled for replay, reducing bundle size for others.

### npm setup

Ensure your bundler supports dynamic imports (code splitting). Most modern bundlers do:

- **Webpack**: [Code splitting docs](https://webpack.js.org/guides/code-splitting/#dynamic-imports)
- **Esbuild**: [Splitting option](https://esbuild.github.io/api/#splitting)
- **Rollup**: [Code splitting docs](https://rollupjs.org/tutorial/#code-splitting)
- **Parcel**: [Code splitting docs](https://parceljs.org/features/code-splitting)

### CDN setup

No code changes needed. The SDK dynamically loads an additional chunk when recording (e.g., `datadogRecorder-<hash>-datadog-rum.js`). Update CSP `script-src` rules if needed to allow the chunk.

## Step 5: Review behavioral changes (no code required, but may need attention)

| Change                                       | Impact                                                                                                             | Action if needed                                                        |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| IE11 support dropped                         | SDK built with ES2018 target. Polyfills removed.                                                                   | Keep using v5 if IE11 support is required.                              |
| Long Animation Frames replace Long Tasks     | On supported browsers, Long Animation Frames are collected instead of Long Tasks. Event type is still `long_task`. | Review if you inspect long task event details.                          |
| Session cookie expiration extended to 1 year | Supports anonymous user tracking.                                                                                  | Set `trackAnonymousUser: false` to opt out.                             |
| `RegExp` and `Event` objects sanitized       | These are no longer serialized as-is in context/attributes.                                                        | Use string representations if you were passing RegExp or Event objects. |
| Webpack `ChunkLoadError` no longer collected | Reduces noise from SDK chunk loading failures.                                                                     | No action needed.                                                       |

## Step 6: Update infrastructure

- **Browser support**: ES2018 baseline. IE11 is no longer supported.
- **CORS**: Add `tracestate` to your existing `Access-Control-Allow-Headers` if using the `tracecontext` propagator (do not replace the full list): `Access-Control-Allow-Headers: <existing-headers>, traceparent, tracestate`
- **CSP**: Allow the dynamically loaded Session Replay chunk (e.g., `datadogRecorder-*-datadog-rum.js`) in `script-src` rules.
- **Bundler config**: Ensure your bundler supports dynamic imports for Session Replay lazy loading.

## Common Mistakes

| Mistake                                                                           | What goes wrong                                                                                           | Fix                                                                                                                |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Defensively disabling `trackUserInteractions`, `trackResources`, `trackLongTasks` | Disables features the project needs — these now default to `true`, which is usually the desired behavior  | Only set these to `false` if the project explicitly did not want them; leave them unset to accept the new defaults |
| Missing `tracestate` in `Access-Control-Allow-Headers`                            | The `tracecontext` propagator now sends a `tracestate` header — cross-origin requests are blocked by CORS | Add `tracestate` alongside `traceparent` in your server's `Access-Control-Allow-Headers`                           |
| Not updating CSP `script-src` for the lazy-loaded Session Replay chunk            | Recording silently fails on CSP-restricted pages — the dynamic chunk is blocked                           | Allow `datadogRecorder-*-datadog-rum.js` in `script-src`                                                           |

## Verification checklist

After upgrading, confirm:

- [ ] SDK loads without console errors
- [ ] No references to removed options (`useCrossSiteSessionCookie`, `sendLogsAfterSessionExpiration`)
- [ ] Session Replay recordings working (if used)
- [ ] Distributed tracing working (no CORS errors from `tracestate` header)
- [ ] Bundle size decreased (IE11 polyfills removed)
- [ ] Long tasks still collected (now as Long Animation Frames on supported browsers)
- [ ] No TypeScript errors from `site` parameter typing

© datadog-labs · MIT · datadog-labs/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set41

The whole set →
triage-flaky-test triage-flaky-test investigates flaky test failures via Datadog, checks failure patterns, and recommends quarantine or a fix. CX Codex +1 362installs datadog-app Guides building Datadog Apps with TypeScript and React. Fetches dynamic documentation straight from the Datadog API. CX Codex +1 302installs agent-observability-build-eval-from-annotations agent-observability-build-eval-from-annotations fits a Datadog LLM-Obs evaluator to human labels using iterative error analysis. Scales manual queue reviews into an automated LLM judge. CX Codex +1 254installs agent-observability-online-experiment The agent-observability-online-experiment skill initiates online experiments, or A/B tests, for LLM applications within Claude Code. It allows comparing prompt or model versions using live traffic. CX Codex +1 170installs dd-product-recommender The dd-product-recommender skill analyzes codebases and project goals to recommend fitting Datadog products. CX Codex +1 130installs upgrade-browser-sdk-v5 The upgrade-browser-sdk-v5 Claude Code skill guides a Datadog Browser SDK upgrade from v4 to v5. It applies when a project still uses retired options, APIs, or CDN paths containing /v4/. CX Codex +1 124installs dd-instrument-rum The dd-instrument-rum Claude Code skill configures Datadog Browser RUM in web applications. It activates for requests to add, repair, or check RUM, Browser Monitoring, or Session Replay. CX Codex +1 116installs dd-account-setup The dd-account-setup Claude Code skill checks Datadog credentials and the account region. It runs before Datadog setup or instrumentation, and can address a 403 caused by a region mismatch. CX Codex +1 113installs

Project sponsors

Companies that keep this analytics open