You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This RFC proposes merging the [sentry-javascript-bundler-plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins) repository into the [sentry-javascript](https://github.com/getsentry/sentry-javascript) monorepo. This consolidation will unify versioning (shipping majors together), reduce maintenance overhead, and improve the developer experience for both maintainers and users.
18
+
This RFC proposes merging the [sentry-javascript-bundler-plugins](https://github.com/getsentry/sentry-javascript-bundler-plugins) repository into the [sentry-javascript](https://github.com/getsentry/sentry-javascript) monorepo. This consolidation will unify versioning, reduce maintenance overhead, and improve the developer experience for both maintainers and users.
19
19
20
20
# Motivation
21
21
@@ -24,222 +24,113 @@ The bundler plugins (`@sentry/webpack-plugin`, `@sentry/vite-plugin`, `@sentry/r
24
24
1.**Versioning complexity**: Independent release cycles make it difficult to ensure compatibility between SDK and plugins.
25
25
2.**Testing limitations**: Cannot easily test plugins against the actual SDK code they'll be bundling.
26
26
3.**Contributor friction**: Developers working on cross-boundary features need to context-switch between repositories.
27
-
4.**User confusion**: Users often expect bundler plugins to live in the main SDK repository and file issues in the wrong place.
27
+
4.**User confusion**: Users often file issues in the wrong repository.
28
28
5.**Duplicate infrastructure**: Separate CI/CD pipelines, release processes, and tooling configurations.
29
-
6.**Triaging overhead**: Issues split across repositories complicates tracking and prioritization.
- Test plugins with the actual SDK code they'll bundle
35
-
- Simplify the release process to a single Craft configuration
36
-
- Provide better tooling support (including LLM/AI context) for cross-boundary development
37
-
- Consolidate issue triaging with labels
38
29
39
30
# Background
40
31
41
-
The bundler plugins were originally developed in a separate repository (during hackweek) to allow independent versioning and release cycles. The plugins are built on [unplugin](https://github.com/unjs/unplugin) and provide:
42
-
43
-
- Sourcemap upload to Sentry
44
-
- Release creation and management
45
-
- Automatic release name discovery
46
-
- Release injection for automatic error association
47
-
- React component display names for breadcrumbs and Session Replays
32
+
The bundler plugins were originally developed in a separate repository to allow independent versioning. The plugins are built on [unplugin](https://github.com/unjs/unplugin) and provide sourcemap upload, release creation/management, release injection, and React component display names for breadcrumbs and Session Replays.
In a future phase (not part of this RFC), consolidate all plugins into a single `@sentry/bundler-plugins` package with subpath exports:
51
+
# Options Considered
118
52
119
-
```
120
-
@sentry/bundler-plugins/webpack
121
-
@sentry/bundler-plugins/vite
122
-
@sentry/bundler-plugins/rollup
123
-
@sentry/bundler-plugins/esbuild
124
-
```
53
+
## Option 1: Merge into sentry-javascript monorepo (Recommended)
125
54
126
-
This would require cross-publishing/aliasing to existing package names for backwards compatibility.
55
+
Move all bundler plugin packages into the `sentry-javascript` repository. A two-phase approach (preparatory work in original repo, then final merge) reduces risk and allows changes to be tested in isolation.
127
56
128
57
## Option 2: Keep repositories separate
129
58
130
59
Maintain the current separate repository structure.
131
60
132
61
**Rejected because**: Does not address the core issues of versioning complexity, testing limitations, and contributor friction.
133
62
134
-
# Implementation Strategy
63
+
# Implementation Plan
135
64
136
65
## Prerequisites
137
66
138
-
-[x] Verify license compatibility (both MIT ✅)
139
-
-[ ] Gather Webpack 4 usage statistics to inform support decision
## Phase 1: Preparation (in sentry-javascript-bundler-plugins repo)
149
71
150
-
1.**Copy packages**: Move packages into `sentry-javascript/packages/` directory
151
-
- Option A: Flat structure alongside other packages
152
-
- Option B: Nested under `packages/bundler-plugins/` subdirectory (preferred?)
72
+
On a dedicated branch (e.g., `merge-prep`):
153
73
154
-
2.**Integrate with sentry-javascript's monorepo setup**: Adapt package configurations to match target repo's build system
74
+
1.**Update dependencies**:
75
+
- Bump minimum Node.js to 18+
76
+
- Migrate unplugin to v2 (drops Node 16 and Webpack 4 support)
77
+
- Bump Sentry CLI to v3
78
+
2.**Migrate tests from Jest to Vitest**
79
+
3.**Audit dependencies** for conflicts with sentry-javascript
80
+
4.**Publish final standalone version** with deprecation notice
155
81
156
-
3.**Migrate tests**: Convert Jest tests to Vitest
157
-
- Update test configuration
158
-
- Migrate Jest-specific APIs to Vitest equivalents
159
-
- Ensure test coverage is maintained
82
+
## Phase 2: Migration to sentry-javascript
160
83
161
-
4.**Update dependencies**:
162
-
- Bump minimum Node.js version to 18+
163
-
- Update unplugin to latest version
164
-
- Remove Node 16 compatibility workarounds
84
+
1.**Copy packages** into `sentry-javascript/packages/` (flat structure or nested under `packages/bundler-plugins/`)
85
+
2.**Integrate with monorepo** build system and CI
86
+
3.**Update `.craft.yml`** for new release targets
165
87
166
-
5.**Configure CI**: Add bundler plugin jobs to GitHub Actions
167
-
- Build bundler plugins in parallel job (doesn't impact overall CI time)
168
-
- Integration tests with actual SDK code
88
+
## Phase 3: Release
169
89
170
-
## Phase 3: Publishing Configuration
90
+
1.**Ship with sentry-javascript v11** to accommodate breaking changes
91
+
2.**Communication**: Deprecation notice on old repo, update documentation
171
92
172
-
1.**Update `.craft.yml`** for new release targets
93
+
## Phase 4: Post-Migration
173
94
174
-
2.**Version synchronization**: Configure packages to use SDK version numbers
95
+
1.**Archive**`sentry-javascript-bundler-plugins` with README pointing to monorepo
175
96
176
-
3.**GitHub Actions**: Update release workflows to include bundler plugin packages
97
+
# Breaking Changes
177
98
178
-
## Phase 4: Release
99
+
Released with v11:
179
100
180
-
1.**Major version release**: First unified release as part of sentry-javascript v11
101
+
1.**Node.js 16 dropped** - Minimum version increased to 18+
102
+
2.**Webpack 4 dropped** (pending usage stats) - Required by unplugin v2; Webpack 5 was released 5+ years ago
103
+
3.**Version number jump** - Plugins jump from v4.x to v11.x to align with SDK
181
104
182
-
2.**Communication**:
183
-
- Deprecation notice on old repository
184
-
- Migration guide for users (anything to do here?)
185
-
- Update documentation
105
+
# Versioning Strategy
186
106
187
-
## Phase 5: Post-Migration
107
+
-**Major versions**: Released together with sentry-javascript majors
108
+
-**Minor/Patch versions**: Released together with sentry-javascript (all packages share same version)
188
109
189
-
1.**Archive repository**: Archive `sentry-javascript-bundler-plugins` with README pointing to monorepo
190
-
2.**Cleanup**: Remove any remaining references to old repository
110
+
# Future Considerations (Out of Scope)
191
111
192
-
# Potential Breaking Changes
112
+
Consolidate all plugins into a single `@sentry/bundler-plugins` package with subpath exports (e.g., `@sentry/bundler-plugins/webpack`). Would require aliasing to existing package names for backwards compatibility.
193
113
194
-
This migration will introduce the following breaking changes (to be released with v11):
195
-
196
-
1.**Node.js 16 support dropped**: Minimum Node.js version increased to 18+
197
-
2.**Webpack 4 support dropped** (pending usage stats): Webpack 4 requires `NODE_OPTIONS=--openssl-legacy-provider` on Node 17+; Webpack 5 was released 5+ years ago
198
-
3.**Version number jump**: Plugin packages will jump from v4.x to v11.x to align with SDK versioning
199
-
200
-
# Known Drawbacks
201
-
202
-
1.**Larger monorepo**: Increases repository size and potentially CI times (mitigated by parallel jobs)
203
-
2.**Migration effort**: One-time cost to migrate packages, tests, and configuration
204
-
3.**Version number jump**: Users may be confused by jump from v4.x to v11.x
205
-
4.**Loss of independent releases**: Minor/patch releases tied to SDK schedule (unless Craft is configured otherwise)
206
-
207
-
# Pros and Cons Summary
114
+
# Pros and Cons
208
115
209
116
## Pros
210
117
211
118
- Single source of truth for all JavaScript SDK tooling
212
-
- Consistent versioning across SDK and build tools
- Easier to ensure compatibility between SDK and plugins
215
-
- Can test plugins with actual SDK code they'll bundle
119
+
- Consistent versioning and shared infrastructure
120
+
- Can test plugins with actual SDK code
216
121
- Reduced cognitive load for contributors
217
-
- Simpler dependency management
218
-
- Better triaging with labels (users don't know about separate repo)
219
-
- Shared context for LLMs when developing cross-boundary features
220
-
- All plugin code has minimal impact on repo size
122
+
- Better triaging (users don't know about separate repo)
221
123
222
124
## Cons
223
125
224
-
-Migration effort and potential breaking changes
225
-
- Independent release cycles no longer possible without extra Craft work
126
+
-One-time migration effort
127
+
- Independent release cycles no longer possible without extra Craft configuration
226
128
- Larger monorepo
227
-
- Risk of disrupting existing users during transition
228
-
- Increased complexity in the sentry-javascript repo
229
-
230
-
# Unresolved Questions
231
-
232
-
1.**Independent versioning**: Should we configure Craft to support independent minor/patch releases for bundler plugins, or tie everything to the SDK release schedule? Recommended: Same release cycle
233
-
234
-
2.**Webpack 4 support**: What are the current usage statistics? Should we drop support in v11, or maintain it with workarounds?
235
-
236
-
3.**Sentry CLI v3**: Should the Sentry CLI v3 migration (bundler-plugins issue bundler-plugins issue https://github.com/getsentry/sentry-javascript-bundler-plugins/issues/825) happen before or after the merge?
237
-
238
-
5.**SDK re-exports**: Should we re-export plugins from SDK packages in the future? This ships dev dependencies as prod dependencies, which users have complained about.
129
+
- Version jump from v4.x to v11.x may confuse users
0 commit comments