Skip to content

Commit 1292d6b

Browse files
chargomechargome
authored
rfc(decision): Merge sentry-javascript-bundler-plugins into sentry-javascript (#149)
1 parent 2af766d commit 1292d6b

3 files changed

Lines changed: 139 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.DS_Store

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,3 +70,4 @@ This repository contains RFCs and DACIs. Lost?
7070
- [0141-linking-traces](text/0141-linking-traces.md): Support Linking Traces
7171
- [0146-automatic-in-app-rules](text/0146-automatic-in-app-rules.md): For Java projects, when a code mapping is automatically created, also create an in-app stack trace rules to categorize the frames as in-app
7272
- [0148-logs-for-crashes](text/0148-logs-for-crashes.md): Logs for Crashes
73+
- [0149-merge-bundler-plugins](text/0149-merge-bundler-plugins.md): Merge sentry-javascript-bundler-plugins into sentry-javascript

‎text/0149-merge-bundler-plugins.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
- Start Date: 2026-01-23
2+
- RFC Type: decision
3+
- RFC PR: https://github.com/getsentry/rfcs/pull/149
4+
- RFC Status: draft
5+
- RFC Driver: [Charly Gomez](https://github.com/chargome)
6+
- RFC Approver: JavaScript SDK Team
7+
8+
# Stakeholders
9+
10+
| Role | People |
11+
| -------------------- | ----------------------------------------- |
12+
| Driver | @chargome / JavaScript SDK Team |
13+
| Approver | JavaScript SDK Team |
14+
| Informed (potential) | Docs Team, Other SDK Engineering Managers |
15+
16+
# Summary
17+
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+
20+
# Motivation
21+
22+
The bundler plugins (`@sentry/webpack-plugin`, `@sentry/vite-plugin`, `@sentry/rollup-plugin`, `@sentry/esbuild-plugin`) are tightly coupled to the Sentry JavaScript SDK. Maintaining them in a separate repository creates several pain points:
23+
24+
1. **Versioning complexity**: Independent release cycles make it difficult to ensure compatibility between SDK and plugins.
25+
2. **Testing limitations**: Cannot easily test plugins against the actual SDK code they'll be bundling.
26+
3. **Contributor friction**: Developers working on cross-boundary features need to context-switch between repositories.
27+
4. **User confusion**: Users often file issues in the wrong repository.
28+
5. **Duplicate infrastructure**: Separate CI/CD pipelines, release processes, and tooling configurations.
29+
30+
# Background
31+
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.
33+
34+
## Current State
35+
36+
| Aspect | sentry-javascript-bundler-plugins | sentry-javascript |
37+
| --------------- | --------------------------------- | ----------------- |
38+
| License | MIT | MIT |
39+
| Current Version | v4.x | v9.x |
40+
| Test Framework | Jest | Vitest |
41+
| Node.js Minimum | Node 16 | Node 18+ |
42+
| Monorepo Tool | Nx | Nx |
43+
44+
**Packages to migrate:**
45+
- `@sentry/bundler-plugin-core`
46+
- `@sentry/webpack-plugin`
47+
- `@sentry/vite-plugin`
48+
- `@sentry/rollup-plugin`
49+
- `@sentry/esbuild-plugin`
50+
51+
# Options Considered
52+
53+
## Option 1: Merge into sentry-javascript monorepo (Recommended)
54+
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.
56+
57+
## Option 2: Keep repositories separate
58+
59+
Maintain the current separate repository structure.
60+
61+
**Rejected because**: Does not address the core issues of versioning complexity, testing limitations, and contributor friction.
62+
63+
# Implementation Plan
64+
65+
## Prerequisites
66+
67+
- [x] Verify license compatibility (both MIT)
68+
69+
## Phase 1: Preparation (in sentry-javascript-bundler-plugins repo)
70+
71+
On a dedicated branch (e.g., `merge-prep`):
72+
73+
1. **Update dependencies**:
74+
- Bump minimum Node.js to 18+
75+
- Remove unplugin dependency ([POC](https://github.com/getsentry/sentry-javascript-bundler-plugins/pull/858)) - unplugin pins us to specific Node versions
76+
- Bump Sentry CLI to v3
77+
- Replace Rollup v2 build tooling (currently pinned to v2, likely for Node 14 compat) with a modern bundler
78+
2. **Migrate tests from Jest to Vitest**
79+
3. **Fix e2e/integration test isolation** - Tests currently aren't isolated and pick up incorrect bundler versions (e.g., Rollup tests only test Rollup v2 because it's the build dependency, despite us not even supporting Rollup v2). Tests should invoke bundlers in isolated environments rather than calling them from code.
80+
4. **Audit dependencies** for conflicts with sentry-javascript
81+
5. **Publish final standalone version** with deprecation notice
82+
6. **Merge prep branch to main** when ready for migration
83+
84+
## Phase 2: Migration to sentry-javascript
85+
86+
1. **Merge packages** into `sentry-javascript/packages/` while preserving git history (via `git subtree` or [git-filter-repo](https://github.com/newren/git-filter-repo))
87+
2. **Integrate with monorepo** build system and CI
88+
3. **Update `.craft.yml`** for new release targets
89+
90+
## Phase 3: Release
91+
92+
1. **Ship with sentry-javascript v11** to accommodate breaking changes
93+
2. **Communication**: Deprecation notice on old repo, update documentation
94+
95+
## Phase 4: Post-Migration
96+
97+
1. **Archive** `sentry-javascript-bundler-plugins` with README pointing to monorepo
98+
99+
# Breaking Changes
100+
101+
Released with v11:
102+
103+
1. **Node.js 16 dropped** - Minimum version increased to 18+. Note: Node 18 removed support for the MD4 hashing algorithm that webpack v4 relied on, so bumping to Node 18+ effectively drops webpack v4 support as well.
104+
2. **Version number jump** - Plugins jump from v4.x to v11.x to align with SDK
105+
106+
# Versioning Strategy
107+
108+
- **Major versions**: Released together with sentry-javascript majors
109+
- **Minor/Patch versions**: Released together with sentry-javascript (all packages share same version)
110+
111+
# Future Considerations (Out of Scope)
112+
113+
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.
114+
115+
# Pros and Cons
116+
117+
## Pros
118+
119+
- Single source of truth for all JavaScript SDK tooling
120+
- Consistent versioning and shared infrastructure
121+
- Can test plugins with actual SDK code
122+
- Reduced cognitive load for contributors
123+
- Better triaging (users don't know about separate repo)
124+
125+
## Cons
126+
127+
- One-time migration effort
128+
- Independent release cycles no longer possible without extra Craft configuration
129+
- Larger monorepo
130+
- Version jump from v4.x to v11.x may confuse users
131+
132+
# References
133+
134+
- [sentry-javascript-bundler-plugins repository](https://github.com/getsentry/sentry-javascript-bundler-plugins)
135+
- [sentry-javascript repository](https://github.com/getsentry/sentry-javascript)
136+
- [RFC 0086: Sentry Bundler Plugins API](https://github.com/getsentry/rfcs/blob/main/text/0086-sentry-bundler-plugins-api.md)
137+
- [unplugin](https://github.com/unjs/unplugin)

0 commit comments

Comments
 (0)