Deprecating Our Legacy JavaScript SDK

Sentry is full of engineers, so we know how painful it can be to deal with breaking changes caused by third party libraries. But we also know those third party libraries have to continually update and stay on top of their games, or they’ll become irrelevant.

For that reason, we try to only introduce breaking changes when they’re really (really) required. Especially when those changes are made to an API surface.

You can probably guess why we’re writing this: we’re announcing a breaking change. In Q2 2020 (or at least no earlier than that) we will deprecate our old raven-js in favor of the newer @sentry/browser on npm.

Don’t panic

Deprecation doesn’t mean raven-js will stop working. It will, in fact, work as long as Sentry exists (which has been prophesied to last until the sun is blotted out of the sky and the rivers run black with printer ink). It just means a message will pop up when you install the raven-js package guiding you to use the @sentry/browser SDK instead. This is, perhaps, the most gentle breaking change of all time.

If you really want to avoid upgrading, we can’t stop you, but there are lots of very good reasons to upgrade.

Unified API

If you follow our blog closely or use a lot of our SDKs you may have already stumbled upon what we refer to as “Unified SDKs”. The whole idea behind them is bringing our SDKs closer together in terms of how they work and how they’re used.

It shouldn’t feel much different if you are using a Sentry SDK in your frontend using JavaScript or on the backend using Python. Concepts and “language” between SDKs should stay the same and once you know how to use one unified SDK you should be able to use any of the unified SDKs.

Goodbye raven

Let’s look at raven-js vs. @sentry/browser to highlight some benefits of using our new SDKs over the older ones.

Built in TypeScript

The SDKs for JavaScript are written in TypeScript. This isn’t just to help us with development; many other companies use TypeScript in their stack and writing the SDKs in Typescript is arguably a requirement now that libraries provide types for TypeScript. Multiple times in the past our typings have been out of sync with the code, something that was always at risk of happening when it was a manual process with raven-js.

But as @sentry/browser is written in TypeScript it’s now impossible that the typings will be out of sync with the actual code. There are, of course, many more advantages to using TypeScript, but that’s a topic for a different blog post.

Smaller API = Fewer Bugs = More Clarity

The function captureException in raven-js requires two arguments:

captureException: function(error, options)

While this seems perfectly ok at first glance (and certainly has worked very well for many years now) the second argument is a very ambiguous one.

It takes an object, some of the things you can set in there were merged in the event, some options changed the behavior of how we even create the event. It wasn’t clear what exactly is expected to happen without looking at the code, in cases where it worked, fine, but debugging this was a nightmare when it didn’t.

The unified SDKs now separate concerns in a more clear way, Scopes are responsible for enriching context in the event and SDK options alter behavior.

Feature Development

When it comes to supporting the latest, greatest and hippest new JS framework or new product features of Sentry like APM, moving forward if you want to use those new features they will only be introduced in the latest version. Talking about APM specifically the new SDKs were built with having support for APM in mind.

Easy to start, powerful under the hood

The most common and easy tasks using @sentry/browser should be super obvious and shouldn’t require a lot of understanding of the internals of the SDK or even Sentry as a product. But when it comes to customizing the behavior of how the SDK works we wanted also to give the user as much power as ever before while making sure we not have to break our API contract in unforeseen ways. Writing your own integration or changing the transport is as easy as never before.

These are just some of the many examples we gave without even mentioning the countless bug fixes and minor improvements we shipped already in the newer SDKs.

As always, we’re happy to receive your feedback and talk about what you think. Feel free to reach out in the Forums or Github.