rollbar 3.0.0-alpha.3 → 3.0.0-alpha.4

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(cat:*)"
+    ]
+  },
+  "enableAllProjectMcpServers": false
+}

package/CLAUDE.examples.md

@@ -0,0 +1,291 @@
+# Rollbar.js Integration Compatibility Matrix
+
+## Current Project Status
+
+**Objective**: Ensure ALL examples work with the ESM-migrated Rollbar.js library.
+
+**Status**: ESM migration complete, DefinePlugin removed, examples fixed, tests passing with workarounds
+
+**Testing Progress**: 
+- ✅ All Category 1 examples (Node.js/NPM) tested and working
+- ✅ All Category 2 examples tested and working  
+- ✅ All Category 3 examples (HTML) tested and working
+- ✅ 3/5 Category 4 examples tested (requirejs, bower, extension-exceptions)
+- ⏸️ Browser extensions v2/v3 testing PAUSED - moving to next project phase
+
+**Decision**: Examples validation is sufficient to confirm ESM migration success. Moving to Phase 2: Modern Testing & TypeScript Foundation (starting with Karma → Web Test Runner migration)
+
+**Latest Updates**:
+
+- ✅ All source code migrated from CommonJS to ES modules
+- ✅ DefinePlugin strategy eliminated - replaced with proper default modules
+- ✅ All Category 1 examples (with npm dependencies) now build successfully
+- ✅ Test suite issues resolved (API endpoints, timing issues)
+- ⚠️ Bundle size issue identified: local packages produce 3x larger bundles due to webpack including entire UMD
+- 🔧 Workaround: Tests continue using pre-built dist files until yalc or similar solution implemented
+- ✅ Moved test fixtures (error.html, csp-errors.html) from examples/ to test/fixtures/html/ following PR #1241 pattern
+- ✅ Updated karma configuration to include test/fixtures path for HTML files
+- ✅ All browser tests passing after fixture relocation
+- ✅ Fixed references to non-existent `rollbar.umd.nojson.js` → now use `rollbar.umd.js`
+- ✅ Fixed RequireJS example reference to non-existent `rollbar.umd.nojson.min.js` → now uses `rollbar.umd.min.js`
+- ✅ Tested and confirmed working: all Category 3 HTML examples + requirejs + extension-exceptions
+
+**Next Steps**:
+
+- [x] Test Category 3 examples (script.html, snippet.html, test.html, itemsPerMinute.html, include_custom_object.html) ✅ All working
+- [x] Fix test.html reference to non-existent rollbar.umd.nojson.js file → Changed to rollbar.umd.js ✅
+- [x] Fix requirejs/test.html to use rollbar.named-amd.js instead of UMD ✅
+- [x] Test requirejs example ✅ Working
+- [x] Test extension-exceptions example ✅ Working
+- [x] Test bower example ✅ Working (installed via `npx bower install`)
+- [ ] Test remaining Category 4 examples (browser extensions v2/v3) - **PAUSED: Moving to Phase 2**
+- [ ] Implement proper solution for local package testing (yalc)
+- [ ] Create automated integration tests for all examples
+
+## Import/Usage Methods vs Environments
+
+| Environment/Framework | Script Tag<br>`<script>`    | CommonJS<br>`require('rollbar')` | CommonJS Absolute<br>`require('rollbar/src/...')` | ESM<br>`import from 'rollbar'` | ESM Absolute<br>`import from 'rollbar/src/...'` | TypeScript<br>`import` | Dynamic Import<br>`import()` | AMD<br>`require([])`    |
+| --------------------- | --------------------------- | -------------------------------- | ------------------------------------------------- | ------------------------------ | ----------------------------------------------- | ---------------------- | ---------------------------- | ----------------------- |
+| **Browser (Vanilla)** | ✅ rollbar.min.js<br>✅ CDN | ❌                               | ❌                                                | ✅ bundler                     | ✅ browser/rollbar.js                           | ✅ bundler             | ✅ rollbar.umd.js            | ✅ rollbar.named-amd.js |
+| **Node.js**           | ❌                          | ✅ main                          | ✅ server/rollbar.js                              | ✅ main                        | ✅ server/rollbar.js                            | ✅                     | ✅ main                      | ❌                      |
+| **React**             | ✅                          | ✅ bundler                       | ✅ browser/rollbar.js                             | ✅ bundler                     | ✅ browser/rollbar.js                           | ✅ bundler             | ✅ bundler                   | ⚠️                      |
+| **Vue.js**            | ✅                          | ✅ bundler                       | ✅ browser/rollbar.js                             | ✅ bundler                     | ✅ browser/rollbar.js                           | ✅ bundler             | ✅ bundler                   | ⚠️                      |
+| **Angular**           | ❌                          | ❌                               | ❌                                                | ✅                             | ✅ browser/rollbar.js                           | ✅                     | ✅                           | ❌                      |
+| **Next.js (SSR)**     | ❌                          | ✅                               | ✅                                                | ✅                             | ✅                                              | ✅                     | ✅                           | ❌                      |
+| **Webpack**           | ❌                          | ✅                               | ✅                                                | ✅                             | ✅                                              | ✅                     | ✅                           | ✅                      |
+| **React Native**      | ❌                          | ✅                               | ⚠️                                                | ✅                             | ⚠️                                              | ✅                     | ❌                           | ❌                      |
+| **Electron**          | ✅                          | ✅                               | ✅                                                | ✅                             | ✅                                              | ✅                     | ✅                           | ❌                      |
+| **Browser Extension** | ✅                          | ❌                               | ❌                                                | ✅ bundler                     | ✅ browser/rollbar.js                           | ✅ bundler             | ✅                           | ❌                      |
+| **Web Workers**       | ✅                          | ❌                               | ❌                                                | ✅                             | ✅ browser/rollbar.js                           | ✅                     | ✅                           | ❌                      |
+| **RequireJS**         | ❌                          | ❌                               | ❌                                                | ❌                             | ❌                                              | ❌                     | ❌                           | ✅ rollbar.named-amd.js |
+| **Browserify**        | ❌                          | ⚠️                               | ⚠️                                                | ⚠️                             | ⚠️                                              | ⚠️                     | ❌                           | ❌                      |
+| **Bower**             | ⚠️                          | ❌                               | ❌                                                | ❌                             | ❌                                              | ❌                     | ❌                           | ⚠️                      |
+
+## Legend
+
+- ✅ Supported and tested
+- ⚠️ Technically possible but unsupported/not recommended
+- ❌ Not possible/applicable
+
+## Absolute Import Patterns
+
+### CommonJS Absolute Imports
+
+```javascript
+// Browser-side (with bundler)
+const Rollbar = require('rollbar/src/browser/rollbar');
+
+// Server-side
+const Rollbar = require('rollbar/src/server/rollbar');
+```
+
+### ESM Absolute Imports
+
+```javascript
+// Browser-side
+import Rollbar from 'rollbar/src/browser/rollbar';
+
+// Server-side
+import Rollbar from 'rollbar/src/server/rollbar';
+```
+
+**Note**: The `.default` is no longer required for CommonJS imports. The package.json conditional exports now handle module format resolution automatically.
+
+## Package Entry Points
+
+### Conditional Exports (Primary)
+
+The package uses conditional exports to provide the correct module format based on the environment:
+
+```json
+"exports": {
+  ".": {
+    "types": "./index.d.ts",
+    "node": {
+      "import": "./src/server/rollbar.js",
+      "require": "./src/server/rollbar.cjs"
+    },
+    "browser": {
+      "import": "./src/browser/rollbar.js",
+      "require": "./dist/rollbar.umd.min.js"
+    },
+    "default": "./dist/rollbar.umd.min.js"
+  }
+}
+```
+
+This means:
+
+- **Node.js + ESM**: `import Rollbar from 'rollbar'` → `src/server/rollbar.js`
+- **Node.js + CommonJS**: `require('rollbar')` → `src/server/rollbar.cjs`
+- **Browser + ESM**: `import Rollbar from 'rollbar'` → `src/browser/rollbar.js`
+- **Browser + CommonJS**: `require('rollbar')` → `dist/rollbar.umd.min.js`
+- **TypeScript**: Uses `index.d.ts` for type definitions
+- **Default/Other**: Falls back to `dist/rollbar.umd.min.js`
+
+### Legacy Fields (Backward Compatibility)
+
+The package still includes legacy fields for older bundlers:
+
+- `"main": "src/server/rollbar.js"` - Node.js entry point
+- `"browser": "dist/rollbar.umd.min.js"` - Browser entry point
+- `"module": "src/browser/rollbar.js"` - ES module entry point
+
+### Direct Import Paths
+
+1. **Source files** (ES modules):
+   - `rollbar/src/server/rollbar.js` - Server-side source
+   - `rollbar/src/browser/rollbar.js` - Browser-side source
+   - `rollbar/src/react-native/rollbar.js` - React Native source
+
+2. **Distribution files** (pre-built bundles):
+   - `rollbar/dist/rollbar.umd.js` - Universal (CommonJS/AMD/global)
+   - `rollbar/dist/rollbar.umd.min.js` - Universal minified
+   - `rollbar/dist/rollbar.js` - Vanilla (script tag only)
+   - `rollbar/dist/rollbar.min.js` - Vanilla minified
+   - `rollbar/dist/rollbar.snippet.js` - Async snippet loader
+   - `rollbar/dist/rollbar.named-amd.js` - AMD/RequireJS
+   - `rollbar/dist/rollbar.named-amd.min.js` - AMD/RequireJS minified
+
+### CDN
+
+`https://cdn.rollbar.com/rollbarjs/refs/tags/v{VERSION}/rollbar.min.js`
+
+## Test Coverage Status
+
+### Category 1: Node.js/NPM Examples with Rollbar Dependency
+
+Priority - these use the library and can break with our changes.
+
+| Example           | Type            | Build Cmd                   | Start Cmd            | Rollbar Dep   | Status                  |
+| ----------------- | --------------- | --------------------------- | -------------------- | ------------- | ----------------------- |
+| `angular/`        | Angular SPA     | `ng build`                  | `ng serve`           | ✅ file:../.. | [✅] Build [✅] Start   |
+| `react/`          | React SPA       | `webpack --mode production` | `webpack-dev-server` | ✅ file:../.. | [✅] Build\* [✅] Start |
+| `vuejs3/`         | Vue.js 3 SPA    | `vite build`                | `vite dev`           | ✅ file:../.. | [✅] Build [✅] Start   |
+| `webpack/`        | Webpack bundler | `webpack`                   | -                    | ✅ file:../.. | [✅] Build\*            |
+| `no-conflict/`    | noConflict mode | `webpack`                   | `node server.js`     | ✅ file:../.. | [✅] Build [✅] Start   |
+| `universal-node/` | SSR Node        | `webpack`                   | `node dist/server`   | ✅ file:../.. | [✅] Build [✅] Start   |
+
+\*Note: React and webpack examples pass build/tests but produce larger bundles when using local package dependency.
+
+### Category 2: Examples Without Rollbar in package.json
+
+Need investigation - they might import rollbar differently.
+
+| Example              | Type            | Build Cmd       | Start Cmd        | Notes                                          | Status       |
+| -------------------- | --------------- | --------------- | ---------------- | ---------------------------------------------- | ------------ |
+| `browserify/`        | Bundler         | `npm run build` | -                | Updated to use `rollbar` package               | [✅] Build   |
+| `universal-browser/` | Browser/Snippet | -               | `node server.js` | Uses Rollbar snippet, loads `/dist/rollbar.js` | [✅] Working |
+
+### Category 3: HTML Examples (No Build System)
+
+Direct script tag usage - critical for CDN users.
+
+| Example                      | Type                 | Status       | Notes                                          |
+| ---------------------------- | -------------------- | ------------ | ---------------------------------------------- |
+| `script.html`                | Basic `<script>` tag | [✅] Working | Uses `rollbar.umd.js`                          |
+| `snippet.html`               | Async snippet        | [✅] Working | Uses snippet to load `/dist/rollbar.js`        |
+| `test.html`                  | Test page            | [✅] Working | Fixed: now uses `rollbar.umd.js` (was nojson)  |
+| `itemsPerMinute.html`        | Rate limiting        | [✅] Working | Tests rate limiting with `rollbar.umd.js`      |
+| `include_custom_object.html` | Custom data          | [✅] Working | Tests transform function with `rollbar.umd.js` |
+
+### Category 4: Special Cases (No package.json)
+
+| Example                 | Type                 | Notes                                               | Status       |
+| ----------------------- | -------------------- | --------------------------------------------------- | ------------ |
+| `browser_extension_v2/` | Chrome ext v2        | Has manifest.json                                   | [ ] Test     |
+| `browser_extension_v3/` | Chrome ext v3        | Has manifest.json                                   | [ ] Test     |
+| `requirejs/`            | AMD loader           | Fixed nojson reference -> uses `rollbar.umd.min.js` | [✅] Working |
+| `bower/`                | Legacy pkg mgr       | Uses `rollbar.snippet.js` via bower_components      | [✅] Working |
+| `extension-exceptions/` | Ad blocker detection | Disables Rollbar if ad blocker detected             | [✅] Working |
+
+### Critical Test Scenarios After ESM Migration
+
+1. **CommonJS in Node.js**: `const Rollbar = require('rollbar')`
+2. **ESM in Node.js**: `import Rollbar from 'rollbar'`
+3. **Browser script tag**: `<script src="dist/rollbar.min.js"></script>`
+4. **Browser with bundler**: Various import methods
+5. **TypeScript**: Type definitions still work
+6. **Framework integrations**: React, Angular, Vue still work
+7. **SSR frameworks**: Next.js dual environment support
+8. **Legacy support**: RequireJS, Bower, Browserify
+
+## Examples Validation
+
+The validation of examples is automated using the `examples/validate.js` script. See [CLAUDE.examples.validate.md](./CLAUDE.examples.validate.md) for implementation details and future automation plans.
+
+## Key Changes Made During ESM Migration
+
+### 1. Removed DefinePlugin Strategy
+
+- Eliminated runtime `package.json` imports that were causing Angular SSR failures
+- Created proper default modules for each platform (`src/defaults.js`, `src/browser/defaults.js`, `src/server/defaults.js`)
+- Removed `defaults.cjs` and the webpack DefinePlugin configuration
+
+### 2. Package.json Updates
+
+- Added `"module": "src/browser/rollbar.js"` field for modern bundler ES module support
+- Removed the entire `defaults` section that was used by DefinePlugin
+- All examples now use `"rollbar": "file:../.."` to test against local package
+
+### 3. Fixed Examples
+
+- **Angular**: Added `"analytics": false` to angular.json to prevent CLI prompts during CI
+- **Vue.js 3**:
+  - Created missing `src/assets/main.css` file
+  - Fixed syntax error in `src/rollbar.js`
+  - Added module field to package.json for Vite compatibility
+- **no-conflict**: Excluded `dist` directory from babel transpilation to prevent babel preset errors
+
+### 4. Known Issues
+
+- **Bundle Size Issue**: Examples using `"rollbar": "file:../.."` produce significantly larger bundles (~3x) compared to npm package versions
+  - Root cause: When using local file dependencies, webpack includes source files that result in larger bundles
+  - Impact: React and webpack examples experienced test timeouts due to bundles growing from ~185KB to ~504KB
+  - Hypothesis: The size increase may be related to the introduction of rrweb for session replay features (not yet verified)
+  - Current workaround: Continue testing with local packages despite the size difference
+
+### 5. Dynamic Example Discovery
+
+- Created `validate-examples.js` script that dynamically finds examples with local rollbar dependency
+- Updated CI workflow to validate all examples automatically
+- `quick-build-test.sh` now dynamically discovers examples based on package.json content
+
+### 6. CommonJS/ESM Interoperability Fix
+
+- Created `src/server/rollbar.cjs` wrapper for CommonJS compatibility
+- Updated package.json with conditional exports:
+  - `"types"` for TypeScript support
+  - `"node"` conditions for import/require
+  - `"browser"` conditions for bundlers
+  - `"default"` fallback to UMD
+- All Category 1 examples now build and run successfully
+
+## Test Fixtures vs Examples
+
+Following the pattern established in [PR #1241](https://github.com/rollbar/rollbar.js/pull/1241), we distinguish between:
+
+### Examples (in `examples/`)
+
+- User-facing demonstrations of SDK integration
+- Meant to be run and understood by developers
+- Should have clear documentation and realistic use cases
+- All files here should be functional examples
+
+### Test Fixtures (in `test/fixtures/`)
+
+- Files used only by the test suite
+- Not meant as examples for users
+- May contain minimal or specialized code for testing specific features
+- Should be organized by type (e.g., `test/fixtures/html/`, `test/fixtures/sourcemaps/`)
+
+**Relocated Files**:
+
+- `error.html` → `test/fixtures/html/error.html` - Used by browser tests to generate errors
+- `csp-errors.html` → `test/fixtures/html/csp-errors.html` - Used to test CSP violation reporting
+
+**Implementation Notes**:
+
+- Updated `Gruntfile.cjs` to include `test/fixtures/**/*.html` pattern for karma file loading
+- Updated test files to reference new paths (`test/fixtures/html/` instead of `examples/`)
+- Added `/test/` proxy in `karma.conf.cjs` for serving fixture files

package/CLAUDE.examples.validate.md

@@ -0,0 +1,97 @@
+# Rollbar.js Examples Validation Automation
+
+## Project Goal
+
+Automate the validation of all Rollbar.js examples to ensure they work correctly with the ESM-migrated library.
+
+## Current Implementation: JavaScript-based Validation
+
+The validation script (`examples/validate.js`) dynamically discovers and validates all examples that use the local Rollbar package.
+
+### How It Works
+
+1. **Dynamic Discovery**: Scans all subdirectories in `examples/` for `package.json` files
+2. **Local Package Detection**: Identifies examples using `"rollbar": "file:../.."`
+3. **Automated Validation**: For each example:
+   - Runs `npm install` to ensure dependencies are resolved
+   - Runs `npm run build` to verify the build process succeeds
+4. **Error Reporting**: Provides clear feedback on which examples fail and why
+
+### Key Features
+
+- **Automatic Example Discovery**: No need to manually maintain a list of examples
+- **Cross-platform Compatibility**: Works on all platforms supporting Node.js
+- **CI/CD Ready**: Exit codes and error reporting suitable for automated workflows
+- **Functional Programming Style**: Uses async/await with proper error handling
+
+### Usage
+
+```bash
+# From the project root
+node examples/validate.js
+
+# Or make it executable
+chmod +x examples/validate.js
+./examples/validate.js
+```
+
+## Definition of "Working"
+
+An example passes validation when:
+
+1. `npm install` succeeds (dependencies resolve correctly)
+2. `npm run build` succeeds (no compilation/bundling errors)
+
+## Future Enhancements
+
+### Runtime Validation
+
+Extend the script to also validate runtime behavior:
+
+```javascript
+// Add after build validation
+await npm(['test'], example, name); // If test script exists
+// Or
+await npm(['start'], example, name); // With timeout and health check
+```
+
+### Browser Example Validation
+
+For HTML examples without build systems:
+
+1. Start a local HTTP server
+2. Use Puppeteer/Playwright to load the HTML
+3. Verify Rollbar initializes without errors
+4. Check console for error messages
+
+### Enhanced Reporting
+
+- Generate detailed validation reports
+- Track bundle sizes
+- Compare against baseline metrics
+- Create compatibility matrix
+
+### Parallel Execution
+
+Run validations in parallel for faster CI/CD:
+
+```javascript
+await Promise.all(examples.map(validateExample));
+```
+
+## Integration with CI/CD
+
+The script is designed to work seamlessly in CI environments:
+
+- Returns non-zero exit code on failure
+- Provides clear console output
+- Can be integrated into GitHub Actions workflows
+- Supports filtering specific examples if needed
+
+## Next Steps
+
+1. Add runtime validation capabilities
+2. Implement browser example testing
+3. Add performance metrics collection
+4. Create visual compatibility dashboard
+5. Set up automated regression alerts