globs:

alwaysApply: false

---

# Yarn v1 Dependency Upgrades

## Upgrade Process

**STOP UPGRADE IMMEDIATELY** if upgrading any dependency with `opentelemetry` in the name and the new version or any of its dependencies uses forbidden OpenTelemetry versions.

**FORBIDDEN VERSION PATTERNS:**

- `2.x.x` versions (e.g., `2.0.0`, `2.1.0`)

- `0.2xx.x` versions (e.g., `0.200.0`, `0.201.0`)

When upgrading OpenTelemetry dependencies:

1. Check the dependency's `package.json` after upgrade

2. Verify the package itself doesn't use forbidden version patterns

3. Verify none of its dependencies use `@opentelemetry/*` packages with forbidden version patterns

```

The `yarn info` command provides detailed dependency information without requiring installation, making it particularly useful for:

- Verifying OpenTelemetry packages don't introduce forbidden version patterns (`2.x.x` or `0.2xx.x`)

- Checking what dependencies a package will bring in before upgrading

- Understanding package version history and compatibility

**CRITICAL**: All changes must pass these checks before committing:

1. **Always run `yarn lint`** - Fix all linting issues

2. **Always run `yarn test`** - Ensure all tests pass

3. **Always run `yarn build:dev`** - Verify TypeScript compilation

## Development Commands

### Build Commands

- `yarn build` - Full production build with package verification

- `yarn build:dev` - Development build (transpile + types)

- `yarn build:dev:watch` - Development build in watch mode (recommended)

- `yarn build:bundle` - Build browser bundles only

### Testing

- `yarn test` - Run all unit tests

### Linting and Formatting

- `yarn lint` - Run ESLint and Prettier checks

- `yarn fix` - Auto-fix linting and formatting issues

- `yarn lint:es-compatibility` - Check ES compatibility

This repository uses **Git Flow**. See [docs/gitflow.md](docs/gitflow.md) for details.

### Key Rules

- **All PRs target `develop` branch** (NOT `master`)

- `master` represents the last released state

- Never merge directly into `master` (except emergency fixes)

- Avoid changing `package.json` files on `develop` during pending releases

- Never update dependencies, package.json content or build scripts unless explicitly asked for

- When asked to do a task on a set of files, always make sure that all occurences in the codebase are covered. Double check that no files have been forgotten.

- Unless explicitly asked for, make sure to cover all files, including files in `src/` and `test/` directories.

### Branch Naming

- Features: `feat/descriptive-name`

- Releases: `release/X.Y.Z`

This is a Lerna monorepo with 40+ packages in the `@sentry/*` namespace.

### Core Packages

- `packages/core/` - Base SDK with interfaces, type definitions, core functionality

- `packages/types/` - Shared TypeScript type definitions - this is deprecated, never modify this package

- `packages/browser-utils/` - Browser-specific utilities and instrumentation

- `packages/node-core/` - Node Core SDK which contains most of the node-specific logic, excluding OpenTelemetry instrumentation.

### Platform SDKs

- `packages/browser/` - Browser SDK with bundled variants

- `packages/node/` - Node.js SDK. All general Node code should go into node-core, the node package itself only contains OpenTelemetry instrumentation on top of that.

- `packages/bun/`, `packages/deno/`, `packages/cloudflare/` - Runtime-specific SDKs

### Framework Integrations

- Framework packages: `packages/{framework}/` (react, vue, angular, etc.)

- Client/server entry points where applicable (nextjs, nuxt, sveltekit)

- Integration tests use Playwright (Remix, browser-integration-tests)

### User Experience Packages

- `packages/replay-internal/` - Session replay functionality

- `packages/replay-canvas/` - Canvas recording for replay

- `packages/replay-worker/` - Web worker support for replay

- `packages/feedback/` - User feedback integration

### Development Packages (`dev-packages/`)

- `browser-integration-tests/` - Playwright browser tests

- `e2e-tests/` - End-to-end tests for 70+ framework combinations

- `node-integration-tests/` - Node.js integration tests

## Development Guidelines

### Build System

- Uses Rollup for bundling (`rollup.*.config.mjs`)

- TypeScript with multiple tsconfig files per package

- Lerna manages package dependencies and publishing

- Vite for testing with `vitest`

### Package Structure Pattern

Each package typically contains:

- `src/index.ts` - Main entry point

- `src/sdk.ts` - SDK initialization logic

- `rollup.npm.config.mjs` - Build configuration

- `tsconfig.json`, `tsconfig.test.json`, `tsconfig.types.json`

- `test/` directory with corresponding test files

### Key Development Notes

- Uses Volta for Node.js/Yarn version management

- Requires initial `yarn build` after `yarn install` for TypeScript linking

- Integration tests use Playwright extensively

- Never change the volta, yarn, or package manager setup in general unless explicitly asked for

### Notes for Background Tasks

- Make sure to use [volta](https://volta.sh/) for development. Volta is used to manage the node, yarn and pnpm version used.

- Make sure that [PNPM support is enabled in volta](https://docs.volta.sh/advanced/pnpm). This means that the `VOLTA_FEATURE_PNPM` environment variable has to be set to `1`.

- Yarn, Node and PNPM have to be used through volta, in the versions defined by the volta config. NEVER change any versions unless explicitly asked to.

## Testing Single Packages

- Test specific package: `cd packages/{package-name} && yarn test`

- Build specific package: `yarn build:dev:filter @sentry/{package-name}`

## Code Style Rules

- Follow existing code conventions in each package

- Check imports and dependencies - only use libraries already in the codebase

- Look at neighboring files for patterns and style

- Never introduce code that exposes secrets or keys

- Follow security best practices

## Before Every Commit Checklist

1. ✅ `yarn lint` (fix all issues)

2. ✅ `yarn test` (all tests pass)

3. ✅ `yarn build:dev` (builds successfully)

4. ✅ Target `develop` branch for PRs (not `master`)

## Documentation Sync

**IMPORTANT**: When editing CLAUDE.md, also update .cursor/rules/sdk_development.mdc and vice versa to keep both files in sync.