Skip to content

Commit 664461a

Browse files
HazATclaudeAbhiPrasad
authored
feat: Add CLAUDE.md for Claude Code development guidance (#16660)
## Summary - Add comprehensive development guide for Claude Code - Include build commands, testing, and repository architecture - Document package management and monorepo structure ## Changes - Added `CLAUDE.md` with development workflows - Added Claude Code local settings configuration --------- Co-authored-by: Claude <[email protected]> Co-authored-by: Abhijeet Prasad <[email protected]>
1 parent b94f652 commit 664461a

File tree

3 files changed

+289
-0
lines changed

3 files changed

+289
-0
lines changed

‎.claude/settings.local.json

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"Bash(find:*)",
5+
"Bash(ls:*)",
6+
"Bash(git:*)",
7+
"Bash(yarn:*)",
8+
"WebFetch(domain:github.com)",
9+
"Bash(grep:*)",
10+
"Bash(mv:*)"
11+
],
12+
"deny": []
13+
}
14+
}

‎.cursor/rules/sdk_development.mdc

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
description: Guidelines for working on the Sentry JavaScript SDK monorepo
3+
alwaysApply: true
4+
---
5+
6+
# SDK Development Rules
7+
8+
You are working on the Sentry JavaScript SDK, a critical production SDK used by thousands of applications. Follow these rules strictly.
9+
10+
## Code Quality Requirements (MANDATORY)
11+
12+
**CRITICAL**: All changes must pass these checks before committing:
13+
14+
1. **Always run `yarn lint`** - Fix all linting issues
15+
2. **Always run `yarn test`** - Ensure all tests pass
16+
3. **Always run `yarn build:dev`** - Verify TypeScript compilation
17+
18+
## Development Commands
19+
20+
### Build Commands
21+
- `yarn build` - Full production build with package verification
22+
- `yarn build:dev` - Development build (transpile + types)
23+
- `yarn build:dev:watch` - Development build in watch mode (recommended)
24+
- `yarn build:dev:filter <package>` - Build specific package and dependencies
25+
- `yarn build:types:watch` - Watch mode for TypeScript types only
26+
- `yarn build:bundle` - Build browser bundles only
27+
28+
### Testing
29+
- `yarn test` - Run all tests (excludes integration tests)
30+
- `yarn test:unit` - Run unit tests only
31+
- `yarn test:pr` - Run tests affected by changes (CI mode)
32+
- `yarn test:pr:browser` - Run affected browser-specific tests
33+
- `yarn test:pr:node` - Run affected Node.js-specific tests
34+
35+
### Linting and Formatting
36+
- `yarn lint` - Run ESLint and Prettier checks
37+
- `yarn fix` - Auto-fix linting and formatting issues
38+
- `yarn lint:es-compatibility` - Check ES compatibility
39+
40+
## Git Flow Branching Strategy
41+
42+
This repository uses **Git Flow**. See [docs/gitflow.md](docs/gitflow.md) for details.
43+
44+
### Key Rules
45+
- **All PRs target `develop` branch** (NOT `master`)
46+
- `master` represents the last released state
47+
- Never merge directly into `master` (except emergency fixes)
48+
- Avoid changing `package.json` files on `develop` during pending releases
49+
50+
### Branch Naming
51+
- Features: `feat/descriptive-name`
52+
- Releases: `release/X.Y.Z`
53+
54+
## Repository Architecture
55+
56+
This is a Lerna monorepo with 40+ packages in the `@sentry/*` namespace.
57+
58+
### Core Packages
59+
- `packages/core/` - Base SDK with interfaces, type definitions, core functionality
60+
- `packages/types/` - Shared TypeScript type definitions (active)
61+
- `packages/browser-utils/` - Browser-specific utilities and instrumentation
62+
63+
### Platform SDKs
64+
- `packages/browser/` - Browser SDK with bundled variants
65+
- `packages/node/` - Node.js SDK with server-side integrations
66+
- `packages/bun/`, `packages/deno/`, `packages/cloudflare/` - Runtime-specific SDKs
67+
68+
### Framework Integrations
69+
- Framework packages: `packages/{framework}/` (react, vue, angular, etc.)
70+
- Client/server entry points where applicable (nextjs, nuxt, sveltekit)
71+
- Integration tests use Playwright (Remix, browser-integration-tests)
72+
73+
### User Experience Packages
74+
- `packages/replay-internal/` - Session replay functionality
75+
- `packages/replay-canvas/` - Canvas recording for replay
76+
- `packages/replay-worker/` - Web worker support for replay
77+
- `packages/feedback/` - User feedback integration
78+
79+
### Development Packages (`dev-packages/`)
80+
- `browser-integration-tests/` - Playwright browser tests
81+
- `e2e-tests/` - End-to-end tests for 70+ framework combinations
82+
- `node-integration-tests/` - Node.js integration tests
83+
- `test-utils/` - Shared testing utilities
84+
- `bundle-analyzer-scenarios/` - Bundle analysis
85+
- `rollup-utils/` - Build utilities
86+
- GitHub Actions packages for CI/CD automation
87+
88+
## Development Guidelines
89+
90+
### Build System
91+
- Uses Rollup for bundling (`rollup.*.config.mjs`)
92+
- TypeScript with multiple tsconfig files per package
93+
- Lerna manages package dependencies and publishing
94+
- Vite for testing with `vitest`
95+
96+
### Package Structure Pattern
97+
Each package typically contains:
98+
- `src/index.ts` - Main entry point
99+
- `src/sdk.ts` - SDK initialization logic
100+
- `rollup.npm.config.mjs` - Build configuration
101+
- `tsconfig.json`, `tsconfig.test.json`, `tsconfig.types.json`
102+
- `test/` directory with corresponding test files
103+
104+
### Key Development Notes
105+
- Uses Volta for Node.js/Yarn version management
106+
- Requires initial `yarn build` after `yarn install` for TypeScript linking
107+
- Integration tests use Playwright extensively
108+
- Native profiling requires Python <3.12 for binary builds
109+
110+
## Testing Single Packages
111+
- Test specific package: `cd packages/{package-name} && yarn test`
112+
- Build specific package: `yarn build:dev:filter @sentry/{package-name}`
113+
114+
## Code Style Rules
115+
- Follow existing code conventions in each package
116+
- Check imports and dependencies - only use libraries already in the codebase
117+
- Look at neighboring files for patterns and style
118+
- Never introduce code that exposes secrets or keys
119+
- Follow security best practices
120+
121+
## Before Every Commit Checklist
122+
1. ✅ `yarn lint` (fix all issues)
123+
2. ✅ `yarn test` (all tests pass)
124+
3. ✅ `yarn build:dev` (builds successfully)
125+
4. ✅ Target `develop` branch for PRs (not `master`)
126+
127+
## Documentation Sync
128+
**IMPORTANT**: When editing CLAUDE.md, also update .cursor/rules/sdk_development.mdc and vice versa to keep both files in sync.

‎CLAUDE.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Development Commands
6+
7+
### Build Commands
8+
9+
- `yarn build` - Full production build with package verification
10+
- `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
13+
- `yarn build:types:watch` - Watch mode for TypeScript types only
14+
- `yarn build:bundle` - Build browser bundles only
15+
16+
### 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
23+
24+
### Linting and Formatting
25+
26+
- `yarn lint` - Run ESLint and Prettier checks
27+
- `yarn fix` - Auto-fix linting and formatting issues
28+
- `yarn lint:es-compatibility` - Check ES compatibility
29+
30+
### Package Management
31+
32+
- `yarn clean` - Clean build artifacts and caches
33+
- `yarn clean:deps` - Clean and reinstall all dependencies
34+
35+
## Repository Architecture
36+
37+
This is a Lerna monorepo containing 40+ packages in the `@sentry/*` namespace. Key architectural components:
38+
39+
### Core Packages
40+
41+
- `packages/core/` - Base SDK with interfaces, type definitions, and core functionality
42+
- `packages/types/` - Shared TypeScript type definitions (active)
43+
- `packages/browser-utils/` - Browser-specific utilities and instrumentation
44+
45+
### Platform SDKs
46+
47+
- `packages/browser/` - Browser SDK with bundled variants
48+
- `packages/node/` - Node.js SDK with server-side integrations
49+
- `packages/bun/`, `packages/deno/`, `packages/cloudflare/` - Runtime-specific SDKs
50+
51+
### 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)
56+
57+
### User Experience Packages
58+
59+
- `packages/replay-internal/` - Session replay functionality
60+
- `packages/replay-canvas/` - Canvas recording support for replay
61+
- `packages/replay-worker/` - Web worker support for replay
62+
- `packages/feedback/` - User feedback integration
63+
64+
### Build System
65+
66+
- Uses Rollup for bundling with config files: `rollup.*.config.mjs`
67+
- TypeScript with multiple tsconfig files per package (main, test, types)
68+
- Lerna manages package dependencies and publishing
69+
- Vite for testing with `vitest`
70+
71+
### Package Structure Pattern
72+
73+
Each package typically contains:
74+
75+
- `src/index.ts` - Main entry point
76+
- `src/sdk.ts` - SDK initialization logic
77+
- `rollup.npm.config.mjs` - Build configuration
78+
- `tsconfig.json`, `tsconfig.test.json`, `tsconfig.types.json` - TypeScript configs
79+
- `test/` directory with corresponding test files
80+
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+
### Key Development Notes
94+
95+
- Uses Volta for Node.js/Yarn version management
96+
- Requires initial `yarn build` after `yarn install` for TypeScript linking
97+
- 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:
121+
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
139+
140+
## 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.

0 commit comments

Comments
 (0)