feat(ember)!: Update to v2 addon format

[aklkv]

Before submitting a pull request, please take a look at our
Contributing guidelines and verify:

• If you've added code that should be tested, please add tests.
• Ensure your code lints and the test suite passes (yarn lint) & (yarn test).
• Link an issue if there is one related to your pull request. If no issue is linked, one will be auto-generated and linked.

Summary

Migrates @sentry/ember from the legacy v1 addon format to the Ember v2 addon format. This modernizes the package to work with both classic Ember builds and Embroider-optimized builds, and removes the runtime dependency on @embroider/macros.

Changes

• Build system: Replaced ember-cli build pipeline with rollup (transpilation → dist/) + tsc (declarations → declarations/)
• Addon entry: Added addon-main.cjs using @embroider/addon-shim as the addon entry point
• Package.json: Set ember-addon.version: 2, updated exports map, added ember-addon.app-js mapping
• Config format: Replaced @embroider/macros getOwnConfig() with explicit Sentry.init() calls and a new setupPerformance() export

API changes:

• init() is now called directly in app.ts or an initializer (no more ENV['@sentry/ember'] config)
• setupPerformance() must be called from an instance-initializer to opt into performance instrumentation
• Initial load instrumentation requires manual <script> tags in index.html
• Added UPGRADE.md with detailed migration guide

Test & CI updates:

• All 21 unit tests passing (acceptance tests for errors, performance, and replay)
• Updated e2e test apps (ember-classic, ember-embroider) to use v2 patterns:
  • Added instance-initializers for performance setup
  • Migrated config from ENV['@sentry/ember'] to Sentry.init() in app.ts
  • Added initial load <script> tags to index.html
• Updated .github/workflows/build.yml CACHED_BUILD_PATHS from packages/ember/*.d.ts to packages/ember/dist + packages/ember/declarations

TypeScript fixes:

• Added "types": ["ember-source/types"] to tsconfig.publish.json for Ember module resolution during declaration generation
• Fixed transition type imports (removed non-existent @ember/routing/-private/transition)
• Simplified instrumentFunction generic to avoid tuple mismatch errors

Breaking Changes

• ENV['@sentry/ember'] config in config/environment.js is no longer supported — use Sentry.init() directly
• Performance instrumentation is no longer automatic — call setupPerformance() from an instance-initializer
• Initial load tracking requires manual <script> tags in app/index.html

Closes JS-217

[nicohrubec]

Hey, thanks for contributing. A few notes:

1. This PR is way too large. Please split it up into smaller pieces so we can review it properly.
2. Is there a way to get this done without introducing breaking changes? If no, then we need to wait with this until our next major.

[aklkv]

Hey, thanks for contributing. A few notes:

1. This PR is way too large. Please split it up into smaller pieces so we can review it properly.
2. Is there a way to get this done without introducing breaking changes? If no, then we need to wait with this until our next major.

Hi @nicohrubec, thanks for the feedback!

I understand the concern about PR size. Unfortunately, the v1 → v2 addon migration is an atomic change — you can't incrementally migrate between formats. The build pipeline, entry point structure, and package.json layout must change together for the addon to function.

That said, the core SDK functionality is unchanged — the same instrumentation, error handling, and performance tracking code. The changes fall into two categories:

1. Consumer-facing setup — how users configure the SDK (direct Sentry.init() calls instead of ENV['@sentry/ember'])
2. Build/packaging scaffolding — the surrounding v2 addon infrastructure (Rollup config, addon-main.cjs, exports map, etc.)

The actual instrumentation logic in src/ is largely untouched. So while the diff is large, most of it is build tooling and test app updates to match the new setup pattern — not changes to Sentry functionality itself.

I'm happy to:

• Add a review guide in the PR description highlighting which files contain meaningful changes vs. scaffolding
• Split into multiple logical commits (build system, config API, test updates) to make review easier

Regarding breaking changes — the v2 format requires explicit Sentry.init() calls, so this would need to target the next major release.

Let me know how you'd like to proceed!

[johanrd]

@aklkv thanks a lot for doing this!🙏

FWIW: While waiting for this, I realized I didn't use the performance part of the addon, and was able to just use the @sentry/browser package without the need of any ember specific addon at all.

That also means that the 'breaking change' mentioned in the PR is a very welcome change to reduce the scope of what is delegated to the 'ember' part of the addon. Most is now just handled by the core apis, which it how it should be👍

(the link to Ember v2 addon format is broken in the pr description, btw)

[NullVoxPopuli]

This is a good PR.

I understand the maintainer's perspective of wanting it split up tho.

The only way to do so would be rearranging the monorepo a bit to make a separate test app package.

This would mean the goal of that PR is to just delete the dummy app from the existing v1 addon.

That will still be a large pr, and i don't really see a way to get better than 2 large prs for this needed work.

Maintainers,
You mentioned breaking change timing - i suspect that is because all packages in this repo are released at once?

May i introduce you to https://github.com/release-plan/release-plan ?
It allows each package to be published independently with correct semver inference based on changes in git (and labels assessing impact on a pr) it helps a lot!

[ijlee2]

I left my review and suggestions for this pull request in aklkv#1.

Here's my message to @aklkv on Ember Discord:

Overall, nice job. I only checked the source code, not the files or configuration for demo-app or tests.

I think it'd help users of @sentry/ember if the only import path that they need to know is the barrel file, and help reviewers of your PR if you split the source code into multiple files. The latter has the benefit of improving the maintainability for the future.

I saw that you pushed a new commit after I was about to open my PR. It's possible that I missed something from your new commit while fixing the merge conflicts.

[aklkv]

I left my review and suggestions for this pull request in aklkv#1.

@ijlee2 this is great 💚 would you mind rebasing pleas, I would be happy integrating this changes

[ijlee2]

I left my review and suggestions for this pull request in aklkv#1.

@ijlee2 this is great 💚 would you mind rebasing pleas, I would be happy integrating this changes

@aklkv Done rebasing.

[mydea]

Hey, I am taking another look over this as we are getting closer to planning the next major, where this could go in.

Ideally, we'd align this more closely with how we handle sentry init in other places as well - which would be, to keep things centralized in Sentry.init(). Is there a way we can make this work reliably? I am thinking of something like this:

// app.ts
export default class App extends Application {
  modulePrefix = config.modulePrefix;
  podModulePrefix = config.podModulePrefix;
  Resolver = Resolver;
}

Sentry.init({
  // ...
  integrations: [
    Sentry.browserTracingIntegration({ emberApp: App })
  ]
});

and somehow derive/wrap the necessary thing inside of this? That would be the ideal solution IMHO, or something along these lines. then we can also get rid of all the async import and special options for performance etc. and just pass this directly to the (ember-specific) browser tracing integration 🤔

[mydea]

Or alternatively, if this cannot be made to work nicely, we could also do this in the initializer, which would be more "sentry native":

import * as Sentry from '@sentry/ember';

export function initialize(appInstance) {
  Sentry.addIntegration(Sentry.browserTracingIntegration({ 
    appInstance,
    // other options here
  }); 
}

this would possibly loose tiny bits of timing info but should overall be likely OK...

Then, we need to export a custom browserTracingIntegration from the ember package here, similar to e.g. the vue browserTracingIntegration, where we can run the actual logic.

[mydea]

I will look into PRing into this PR some changes for this!

[mydea]

honestly if we are doing such a big refactor I'd just drop this stuff as built-in functionality - you can build this yourself if needed but likely for simplicity this can go away.

[aklkv]

@mydea thank you for looking at this PR, I will circle back closer to the end of the week

[mydea]

Kind-of extracted/refactored some of this out into a PR that is backwards compatible: #20702

once this is merged, I'll change this PR to use this instead, which should reduce the noise in this specific PR and keep things to a minimum. I'll also move the demo-app into a e2e test application, keeping to our general structure of things. then the ember package itself and the changes in this PR should be relatively reasonably small!

[github-actions]

👋 @getsentry/team-javascript-sdks-framework — Please review this PR when you get a chance!

[github-actions]

👋 @getsentry/team-javascript-sdks-framework — Please review this PR when you get a chance!

[mydea]

Opened a PR here towards this branch with some adjustments: aklkv#2

[cursor]

Router mount flag never set

High Severity

The refactor checks routerService._hasMountedSentryPerformanceRouting to avoid double router instrumentation but never sets it to true after registering listeners (the v1 code did). Each browserTracingIntegration afterAllSetup run attaches duplicate routeWillChange/routeDidChange handlers, causing duplicated navigation/pageload transactions.

 

^{Reviewed by Cursor Bugbot for commit 44712d2. Configure here.}

[cursor]

FastBoot guard removed

Medium Severity

The built-in instance initializer used to skip performance setup when service:fastboot isFastBoot is true. instrumentAppInstancePerformance has no equivalent guard, so SSR/FastBoot app instances can still register browser tracing and router listeners on the server despite UPGRADE.md claiming automatic FastBoot detection.

 

^{Reviewed by Cursor Bugbot for commit 44712d2. Configure here.}

[cursor]

Missing macros runtime dependency

High Severity

browserTracingIntegration still imports @embroider/macros (isTesting, macroCondition), but v2 package.json no longer lists that package under dependencies and publish Babel config does not macro-strip it. Apps without @embroider/macros can fail at module load after upgrading.

 

^{Reviewed by Cursor Bugbot for commit 44712d2. Configure here.}

[sentry]

Bug: The guard _hasMountedSentryPerformanceRouting in instrumentEmberAppInstanceForPerformance is never set, causing duplicate event listeners to be registered on multiple calls, especially in tests.
_{Severity: HIGH}

Suggested Fix

After the guard check at line 36, add the statement routerService._hasMountedSentryPerformanceRouting = true;. This will ensure that the instrumentation logic and event listener registration only run once per routerService instance, as intended by the existing guard mechanism.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: packages/ember/src/utils/instrumentEmberAppInstanceForPerformance.ts#L36-L38

Potential issue: The function `instrumentEmberAppInstanceForPerformance` includes a
guard `if (routerService._hasMountedSentryPerformanceRouting)` to prevent
re-initialization. However, the flag `_hasMountedSentryPerformanceRouting` is never set
to `true` after the check. Consequently, every call to this function, such as during
Ember's instance-initializers in test environments, will re-register `'routeWillChange'`
and `'routeDidChange'` event listeners. This leads to the creation of duplicate spans
for each route change and corrupted transaction data being sent to Sentry, along with
performance degradation from the redundant instrumentation.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 6 total unresolved issues (including 4 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 52d4ffa. Configure here.}

[cursor]

Wrong name on loading routes

Medium Severity

getCurrentScope().setTransactionName runs before transitionIsIntermediate returns, so intermediate loading/error transitions can overwrite the active transaction name (e.g. route:*.loading) used for errors captured during that transition.

 

^{Reviewed by Cursor Bugbot for commit 52d4ffa. Configure here.}

[cursor]

FastBoot guard removed

High Severity

The v1 instance initializer skipped performance setup when service:fastboot reported FastBoot; that guard was removed with no replacement in instrumentAppInstancePerformance, yet the upgrade guide still claims FastBoot is detected automatically.

 

^{Reviewed by Cursor Bugbot for commit 52d4ffa. Configure here.}

[sentry]

Bug: The guard _hasMountedSentryPerformanceRouting is checked but never set, allowing duplicate event listeners if instrumentEmberAppInstanceForPerformance is called multiple times.
_{Severity: MEDIUM}

Suggested Fix

Set the _hasMountedSentryPerformanceRouting property on the router service to true within the instrumentEmberAppInstanceForPerformance function after the initial setup is complete. This will ensure the guard correctly prevents the function's logic from running more than once.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: packages/ember/src/utils/browserTracingIntegration.ts#L81-L91

Potential issue: The function `instrumentEmberAppInstanceForPerformance` includes a
check on the `_hasMountedSentryPerformanceRouting` property to prevent duplicate
initialization and the registration of multiple event listeners. However, this property
is never set to `true` anywhere in the codebase. As a result, this guard is ineffective.
If `instrumentEmberAppInstanceForPerformance` is invoked more than once through any code
path, it will lead to the registration of duplicate event listeners, potentially causing
performance issues or incorrect behavior.

[mydea]

There are a bunch of bot review comments, most of them seem reasonable/accurate to me to work through!