|
2 | 2 |
|
3 | 3 | This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
4 | 4 |
|
| 5 | +# SDK Development Rules |
| 6 | + |
| 7 | +You are working on the Sentry JavaScript SDK, a critical production SDK used by thousands of applications. Follow these rules strictly. |
| 8 | + |
| 9 | +## Code Quality Requirements (MANDATORY) |
| 10 | + |
| 11 | +**CRITICAL**: All changes must pass these checks before committing: |
| 12 | + |
| 13 | +1. **Always run `yarn lint`** - Fix all linting issues |
| 14 | +2. **Always run `yarn test`** - Ensure all tests pass |
| 15 | +3. **Always run `yarn build:dev`** - Verify TypeScript compilation |
| 16 | + |
5 | 17 | ## Development Commands |
6 | 18 |
|
7 | 19 | ### Build Commands |
8 | | - |
9 | 20 | - `yarn build` - Full production build with package verification |
10 | 21 | - `yarn build:dev` - Development build (transpile + types) |
11 | | -- `yarn build:dev:watch` - Development build in watch mode (recommended for development) |
12 | | -- `yarn build:dev:filter <package>` - Build specific package and its dependencies |
| 22 | +- `yarn build:dev:watch` - Development build in watch mode (recommended) |
| 23 | +- `yarn build:dev:filter <package>` - Build specific package and dependencies |
13 | 24 | - `yarn build:types:watch` - Watch mode for TypeScript types only |
14 | 25 | - `yarn build:bundle` - Build browser bundles only |
15 | 26 |
|
16 | 27 | ### Testing |
17 | | - |
18 | | -- `yarn test` - Run all tests (excludes integration tests) |
19 | | -- `yarn test:unit` - Run unit tests only |
20 | | -- `yarn test:pr` - Run tests affected by changes (CI mode) |
21 | | -- `yarn test:pr:browser` - Run affected browser-specific tests |
22 | | -- `yarn test:pr:node` - Run affected Node.js-specific tests |
| 28 | +- `yarn test` - Run all unit tests |
23 | 29 |
|
24 | 30 | ### Linting and Formatting |
25 | | - |
26 | 31 | - `yarn lint` - Run ESLint and Prettier checks |
27 | 32 | - `yarn fix` - Auto-fix linting and formatting issues |
28 | 33 | - `yarn lint:es-compatibility` - Check ES compatibility |
29 | 34 |
|
30 | | -### Package Management |
| 35 | +## Git Flow Branching Strategy |
| 36 | + |
| 37 | +This repository uses **Git Flow**. See [docs/gitflow.md](docs/gitflow.md) for details. |
31 | 38 |
|
32 | | -- `yarn clean` - Clean build artifacts and caches |
33 | | -- `yarn clean:deps` - Clean and reinstall all dependencies |
| 39 | +### Key Rules |
| 40 | +- **All PRs target `develop` branch** (NOT `master`) |
| 41 | +- `master` represents the last released state |
| 42 | +- Never merge directly into `master` (except emergency fixes) |
| 43 | +- Avoid changing `package.json` files on `develop` during pending releases |
| 44 | +- Never update dependencies, package.json content or build scripts unless explicitly asked for |
| 45 | +- 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. |
| 46 | +- Unless explicitly asked for, make sure to cover all files, including files in `src/` and `test/` directories. |
| 47 | + |
| 48 | +### Branch Naming |
| 49 | +- Features: `feat/descriptive-name` |
| 50 | +- Releases: `release/X.Y.Z` |
34 | 51 |
|
35 | 52 | ## Repository Architecture |
36 | 53 |
|
37 | | -This is a Lerna monorepo containing 40+ packages in the `@sentry/*` namespace. Key architectural components: |
| 54 | +This is a Lerna monorepo with 40+ packages in the `@sentry/*` namespace. |
38 | 55 |
|
39 | 56 | ### Core Packages |
40 | | - |
41 | | -- `packages/core/` - Base SDK with interfaces, type definitions, and core functionality |
42 | | -- `packages/types/` - Shared TypeScript type definitions (active) |
| 57 | +- `packages/core/` - Base SDK with interfaces, type definitions, core functionality |
| 58 | +- `packages/types/` - Shared TypeScript type definitions - this is deprecated, never modify this package |
43 | 59 | - `packages/browser-utils/` - Browser-specific utilities and instrumentation |
| 60 | +- `packages/node-core/` - Node Core SDK which contains most of the node-specific logic, excluding OpenTelemetry instrumentation. |
44 | 61 |
|
45 | 62 | ### Platform SDKs |
46 | | - |
47 | 63 | - `packages/browser/` - Browser SDK with bundled variants |
48 | | -- `packages/node/` - Node.js SDK with server-side integrations |
| 64 | +- `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. |
49 | 65 | - `packages/bun/`, `packages/deno/`, `packages/cloudflare/` - Runtime-specific SDKs |
50 | 66 |
|
51 | 67 | ### Framework Integrations |
52 | | - |
53 | | -- Framework packages follow naming: `packages/{framework}/` (react, vue, angular, etc.) |
54 | | -- Each has client/server entry points where applicable (e.g., nextjs, nuxt, sveltekit) |
55 | | -- Integration tests use Playwright (e.g., Remix, browser-integration-tests) |
| 68 | +- Framework packages: `packages/{framework}/` (react, vue, angular, etc.) |
| 69 | +- Client/server entry points where applicable (nextjs, nuxt, sveltekit) |
| 70 | +- Integration tests use Playwright (Remix, browser-integration-tests) |
56 | 71 |
|
57 | 72 | ### User Experience Packages |
58 | | - |
59 | 73 | - `packages/replay-internal/` - Session replay functionality |
60 | | -- `packages/replay-canvas/` - Canvas recording support for replay |
| 74 | +- `packages/replay-canvas/` - Canvas recording for replay |
61 | 75 | - `packages/replay-worker/` - Web worker support for replay |
62 | 76 | - `packages/feedback/` - User feedback integration |
63 | 77 |
|
64 | | -### Build System |
| 78 | +### Development Packages (`dev-packages/`) |
| 79 | +- `browser-integration-tests/` - Playwright browser tests |
| 80 | +- `e2e-tests/` - End-to-end tests for 70+ framework combinations |
| 81 | +- `node-integration-tests/` - Node.js integration tests |
| 82 | +- `test-utils/` - Shared testing utilities |
| 83 | +- `bundle-analyzer-scenarios/` - Bundle analysis |
| 84 | +- `rollup-utils/` - Build utilities |
| 85 | +- GitHub Actions packages for CI/CD automation |
| 86 | + |
| 87 | +## Development Guidelines |
65 | 88 |
|
66 | | -- Uses Rollup for bundling with config files: `rollup.*.config.mjs` |
67 | | -- TypeScript with multiple tsconfig files per package (main, test, types) |
| 89 | +### Build System |
| 90 | +- Uses Rollup for bundling (`rollup.*.config.mjs`) |
| 91 | +- TypeScript with multiple tsconfig files per package |
68 | 92 | - Lerna manages package dependencies and publishing |
69 | 93 | - Vite for testing with `vitest` |
70 | 94 |
|
71 | 95 | ### Package Structure Pattern |
72 | | - |
73 | 96 | Each package typically contains: |
74 | | - |
75 | 97 | - `src/index.ts` - Main entry point |
76 | 98 | - `src/sdk.ts` - SDK initialization logic |
77 | 99 | - `rollup.npm.config.mjs` - Build configuration |
78 | | -- `tsconfig.json`, `tsconfig.test.json`, `tsconfig.types.json` - TypeScript configs |
| 100 | +- `tsconfig.json`, `tsconfig.test.json`, `tsconfig.types.json` |
79 | 101 | - `test/` directory with corresponding test files |
80 | 102 |
|
81 | | -### Development Packages (`dev-packages/`) |
82 | | - |
83 | | -Separate from main packages, containing development and testing utilities: |
84 | | - |
85 | | -- `browser-integration-tests/` - Playwright browser tests |
86 | | -- `e2e-tests/` - End-to-end tests for 70+ framework combinations |
87 | | -- `node-integration-tests/` - Node.js integration tests |
88 | | -- `test-utils/` - Shared testing utilities |
89 | | -- `bundle-analyzer-scenarios/` - Bundle analysis |
90 | | -- `rollup-utils/` - Build utilities |
91 | | -- GitHub Actions packages for CI/CD automation |
92 | | - |
93 | 103 | ### Key Development Notes |
94 | | - |
95 | 104 | - Uses Volta for Node.js/Yarn version management |
96 | 105 | - Requires initial `yarn build` after `yarn install` for TypeScript linking |
97 | 106 | - Integration tests use Playwright extensively |
98 | | -- Native profiling requires Python <3.12 for binary builds |
99 | | -- Bundle outputs vary - check `build/bundles/` for specific files after builds |
100 | | - |
101 | | -## Git Flow Branching Strategy |
102 | | - |
103 | | -This repository uses **Git Flow** branching model. See [detailed documentation](docs/gitflow.md). |
104 | | - |
105 | | -### Key Points |
106 | | - |
107 | | -- **All PRs target `develop` branch** (not `master`) |
108 | | -- `master` represents the last released state |
109 | | -- Never merge directly into `master` (except emergency fixes) |
110 | | -- Automated workflow syncs `master` → `develop` after releases |
111 | | -- Avoid changing `package.json` files on `develop` during pending releases |
112 | | - |
113 | | -### Branch Naming |
114 | | - |
115 | | -- Features: `feat/descriptive-name` |
116 | | -- Releases: `release/X.Y.Z` |
117 | | - |
118 | | -## Code Quality Requirements |
119 | | - |
120 | | -**CRITICAL**: This is a production SDK used by thousands of applications. All changes must be: |
| 107 | +- Never change the volta, yarn, or package manager setup in general unless explicitly asked for |
121 | 108 |
|
122 | | -### Mandatory Checks |
123 | | - |
124 | | -- **Always run `yarn lint`** - Fix all linting issues before committing |
125 | | -- **Always run `yarn test`** - Ensure all tests pass |
126 | | -- **Run `yarn build`** - Verify build succeeds without errors |
127 | | - |
128 | | -### Before Any Commit |
129 | | - |
130 | | -1. `yarn lint` - Check and fix ESLint/Prettier issues |
131 | | -2. `yarn test` - Run relevant tests for your changes |
132 | | -3. `yarn build:dev` - Verify TypeScript compilation |
133 | | - |
134 | | -### CI/CD Integration |
135 | | - |
136 | | -- All PRs automatically run full lint/test/build pipeline |
137 | | -- Failed checks block merging |
138 | | -- Use `yarn test:pr` for testing only affected changes |
| 109 | +### Notes for Background Tasks |
| 110 | +- Make sure to use [volta](https://volta.sh/) for development. Volta is used to manage the node, yarn and pnpm version used. |
| 111 | +- 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`. |
| 112 | +- 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. |
139 | 113 |
|
140 | 114 | ## Testing Single Packages |
141 | | - |
142 | | -To test a specific package: `cd packages/{package-name} && yarn test` |
143 | | -To build a specific package: `yarn build:dev:filter @sentry/{package-name}` |
144 | | - |
145 | | -## Cursor IDE Integration |
146 | | - |
147 | | -For Cursor IDE users, see [.cursor/rules/sdk_development.mdc](.cursor/rules/sdk_development.mdc) for complementary development rules. |
| 115 | +- Test specific package: `cd packages/{package-name} && yarn test` |
| 116 | +- Build specific package: `yarn build:dev:filter @sentry/{package-name}` |
| 117 | + |
| 118 | +## Code Style Rules |
| 119 | +- Follow existing code conventions in each package |
| 120 | +- Check imports and dependencies - only use libraries already in the codebase |
| 121 | +- Look at neighboring files for patterns and style |
| 122 | +- Never introduce code that exposes secrets or keys |
| 123 | +- Follow security best practices |
| 124 | + |
| 125 | +## Before Every Commit Checklist |
| 126 | +1. ✅ `yarn lint` (fix all issues) |
| 127 | +2. ✅ `yarn test` (all tests pass) |
| 128 | +3. ✅ `yarn build:dev` (builds successfully) |
| 129 | +4. ✅ Target `develop` branch for PRs (not `master`) |
| 130 | + |
| 131 | +## Documentation Sync |
| 132 | +**IMPORTANT**: When editing CLAUDE.md, also update .cursor/rules/sdk_development.mdc and vice versa to keep both files in sync. |
0 commit comments