diff --git a/.cursor/environment.json b/.cursor/environment.json new file mode 100644 index 000000000000..0828f53fbd4a --- /dev/null +++ b/.cursor/environment.json @@ -0,0 +1,12 @@ +{ + "name": "Sentry JavaScript SDK Development", + "install": "curl https://get.volta.sh | bash && export VOLTA_HOME=\"$HOME/.volta\" && export PATH=\"$VOLTA_HOME/bin:$PATH\" && export VOLTA_FEATURE_PNPM=1 && yarn install", + "start": "export VOLTA_HOME=\"$HOME/.volta\" && export PATH=\"$VOLTA_HOME/bin:$PATH\" && export VOLTA_FEATURE_PNPM=1", + "terminals": [ + { + "name": "Development", + "command": "export VOLTA_HOME=\"$HOME/.volta\" && export PATH=\"$VOLTA_HOME/bin:$PATH\" && export VOLTA_FEATURE_PNPM=1 && echo 'Volta setup complete. Node version:' && node --version && echo 'Yarn version:' && yarn --version", + "description": "Main development terminal with Volta environment configured" + } + ] +} diff --git a/.cursor/rules/sdk_dependency_upgrades.mdc b/.cursor/rules/sdk_dependency_upgrades.mdc index 826249108f01..becf0805eb91 100644 --- a/.cursor/rules/sdk_dependency_upgrades.mdc +++ b/.cursor/rules/sdk_dependency_upgrades.mdc @@ -3,6 +3,7 @@ description: Use this rule if you are looking to upgrade a dependency in the Sen globs: alwaysApply: false --- + # Yarn v1 Dependency Upgrades ## Upgrade Process @@ -45,10 +46,12 @@ Avoid upgrading top-level dependencies (defined in `package.json`), especially i **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 @@ -153,6 +156,7 @@ yarn info versions ``` 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 diff --git a/.cursor/rules/sdk_development.mdc b/.cursor/rules/sdk_development.mdc index 988703ddac81..088c94f47a23 100644 --- a/.cursor/rules/sdk_development.mdc +++ b/.cursor/rules/sdk_development.mdc @@ -12,12 +12,13 @@ You are working on the Sentry JavaScript SDK, a critical production SDK used by **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 +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) @@ -26,13 +27,11 @@ You are working on the Sentry JavaScript SDK, a critical production SDK used by - `yarn build:bundle` - Build browser bundles only ### Testing -- `yarn test` - Run all tests (excludes integration tests) -- `yarn test:unit` - Run unit tests only -- `yarn test:pr` - Run tests affected by changes (CI mode) -- `yarn test:pr:browser` - Run affected browser-specific tests -- `yarn test:pr:node` - Run affected Node.js-specific tests + +- `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 @@ -42,12 +41,17 @@ You are working on the Sentry JavaScript SDK, a critical production SDK used by 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` @@ -56,27 +60,33 @@ This repository uses **Git Flow**. See [docs/gitflow.md](docs/gitflow.md) for de 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 (active) +- `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 with server-side integrations +- `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 @@ -88,13 +98,16 @@ This is a Lerna monorepo with 40+ packages in the `@sentry/*` namespace. ## 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 @@ -102,16 +115,25 @@ Each package typically contains: - `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 -- Native profiling requires Python <3.12 for binary builds +- 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 @@ -119,10 +141,12 @@ Each package typically contains: - 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. \ No newline at end of file + +**IMPORTANT**: When editing CLAUDE.md, also update .cursor/rules/sdk_development.mdc and vice versa to keep both files in sync. diff --git a/CLAUDE.md b/CLAUDE.md index 263b9eef97a4..e515c171303e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,24 +2,32 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +# SDK Development Rules + +You are working on the Sentry JavaScript SDK, a critical production SDK used by thousands of applications. Follow these rules strictly. + +## Code Quality Requirements (MANDATORY) + +**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 for development) -- `yarn build:dev:filter ` - Build specific package and its dependencies +- `yarn build:dev:watch` - Development build in watch mode (recommended) +- `yarn build:dev:filter ` - Build specific package and dependencies - `yarn build:types:watch` - Watch mode for TypeScript types only - `yarn build:bundle` - Build browser bundles only ### Testing -- `yarn test` - Run all tests (excludes integration tests) -- `yarn test:unit` - Run unit tests only -- `yarn test:pr` - Run tests affected by changes (CI mode) -- `yarn test:pr:browser` - Run affected browser-specific tests -- `yarn test:pr:node` - Run affected Node.js-specific tests +- `yarn test` - Run all unit tests ### Linting and Formatting @@ -27,44 +35,71 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co - `yarn fix` - Auto-fix linting and formatting issues - `yarn lint:es-compatibility` - Check ES compatibility -### Package Management +## Git Flow Branching Strategy + +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 -- `yarn clean` - Clean build artifacts and caches -- `yarn clean:deps` - Clean and reinstall all dependencies +- Features: `feat/descriptive-name` +- Releases: `release/X.Y.Z` ## Repository Architecture -This is a Lerna monorepo containing 40+ packages in the `@sentry/*` namespace. Key architectural components: +This is a Lerna monorepo with 40+ packages in the `@sentry/*` namespace. ### Core Packages -- `packages/core/` - Base SDK with interfaces, type definitions, and core functionality -- `packages/types/` - Shared TypeScript type definitions (active) +- `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 with server-side integrations +- `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 follow naming: `packages/{framework}/` (react, vue, angular, etc.) -- Each has client/server entry points where applicable (e.g., nextjs, nuxt, sveltekit) -- Integration tests use Playwright (e.g., Remix, browser-integration-tests) +- 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 support for replay +- `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 +- `test-utils/` - Shared testing utilities +- `bundle-analyzer-scenarios/` - Bundle analysis +- `rollup-utils/` - Build utilities +- GitHub Actions packages for CI/CD automation + +## Development Guidelines + ### Build System -- Uses Rollup for bundling with config files: `rollup.*.config.mjs` -- TypeScript with multiple tsconfig files per package (main, test, types) +- 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` @@ -75,73 +110,42 @@ 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` - TypeScript configs +- `tsconfig.json`, `tsconfig.test.json`, `tsconfig.types.json` - `test/` directory with corresponding test files -### Development Packages (`dev-packages/`) - -Separate from main packages, containing development and testing utilities: - -- `browser-integration-tests/` - Playwright browser tests -- `e2e-tests/` - End-to-end tests for 70+ framework combinations -- `node-integration-tests/` - Node.js integration tests -- `test-utils/` - Shared testing utilities -- `bundle-analyzer-scenarios/` - Bundle analysis -- `rollup-utils/` - Build utilities -- GitHub Actions packages for CI/CD automation - ### 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 -- Native profiling requires Python <3.12 for binary builds -- Bundle outputs vary - check `build/bundles/` for specific files after builds +- Never change the volta, yarn, or package manager setup in general unless explicitly asked for -## Git Flow Branching Strategy +### Notes for Background Tasks -This repository uses **Git Flow** branching model. See [detailed documentation](docs/gitflow.md). +- 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. -### Key Points - -- **All PRs target `develop` branch** (not `master`) -- `master` represents the last released state -- Never merge directly into `master` (except emergency fixes) -- Automated workflow syncs `master` → `develop` after releases -- Avoid changing `package.json` files on `develop` during pending releases - -### Branch Naming - -- Features: `feat/descriptive-name` -- Releases: `release/X.Y.Z` - -## Code Quality Requirements - -**CRITICAL**: This is a production SDK used by thousands of applications. All changes must be: - -### Mandatory Checks - -- **Always run `yarn lint`** - Fix all linting issues before committing -- **Always run `yarn test`** - Ensure all tests pass -- **Run `yarn build`** - Verify build succeeds without errors - -### Before Any Commit +## Testing Single Packages -1. `yarn lint` - Check and fix ESLint/Prettier issues -2. `yarn test` - Run relevant tests for your changes -3. `yarn build:dev` - Verify TypeScript compilation +- Test specific package: `cd packages/{package-name} && yarn test` +- Build specific package: `yarn build:dev:filter @sentry/{package-name}` -### CI/CD Integration +## Code Style Rules -- All PRs automatically run full lint/test/build pipeline -- Failed checks block merging -- Use `yarn test:pr` for testing only affected changes +- 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 -## Testing Single Packages +## Before Every Commit Checklist -To test a specific package: `cd packages/{package-name} && yarn test` -To build a specific package: `yarn build:dev:filter @sentry/{package-name}` +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`) -## Cursor IDE Integration +## Documentation Sync -For Cursor IDE users, see [.cursor/rules/sdk_development.mdc](.cursor/rules/sdk_development.mdc) for complementary development rules. +**IMPORTANT**: When editing CLAUDE.md, also update .cursor/rules/sdk_development.mdc and vice versa to keep both files in sync. diff --git a/package.json b/package.json index 591424f91ec5..f2cbefa5faa4 100644 --- a/package.json +++ b/package.json @@ -22,12 +22,12 @@ "clean:all": "run-s clean:build clean:tarballs clean:caches clean:deps clean:watchman", "fix": "run-s fix:prettier fix:lerna", "fix:lerna": "lerna run fix", - "fix:prettier": "prettier \"**/*.{md,css,yml,yaml}\" \"packages/**/**.{ts,js,mjs,cjs,mts,cts,jsx,tsx,astro,vue}\" \"dev-packages/!(e2e-tests)/**/**.{ts,js,mjs,cjs,mts,cts,jsx,tsx,astro,vue}\" --write", + "fix:prettier": "prettier \"**/*.{md,css,yml,yaml,mdc}\" \"packages/**/**.{ts,js,mjs,cjs,mts,cts,jsx,tsx,astro,vue}\" \"dev-packages/!(e2e-tests)/**/**.{ts,js,mjs,cjs,mts,cts,jsx,tsx,astro,vue}\" --write", "changelog": "ts-node ./scripts/get-commit-list.ts", "link:yarn": "lerna exec yarn link", "lint": "run-s lint:prettier lint:lerna", "lint:lerna": "lerna run lint", - "lint:prettier": "prettier \"**/*.{md,css,yml,yaml}\" \"packages/**/**.{ts,js,mjs,cjs,mts,cts,jsx,tsx,astro,vue}\" --check", + "lint:prettier": "prettier \"**/*.{md,css,yml,yaml,mdc}\" \"packages/**/**.{ts,js,mjs,cjs,mts,cts,jsx,tsx,astro,vue}\" --check", "lint:es-compatibility": "lerna run lint:es-compatibility", "dedupe-deps:check": "yarn-deduplicate yarn.lock --list --fail", "dedupe-deps:fix": "yarn-deduplicate yarn.lock", @@ -165,6 +165,13 @@ "options": { "proseWrap": "preserve" } + }, + { + "files": "*.mdc", + "options": { + "parser": "markdown", + "proseWrap": "preserve" + } } ] }