Support different JS runtimes

[AbhiPrasad]

Problem Statement

The Sentry SDK should work with WinterCG-compatible runtimes other than NodeJS. We should build new SDKs for these platforms, or figure out how to adapt our Node SDK to fit them.

The spec: https://github.com/wintercg/proposal-common-minimum-api

• Cloudflare Workers: cloudflare workers support #2484
• Deno: Support for Deno server #3009
• Vercel Edge Runtime: Vercel Edge Runtime SDK #8087
• Next.js middleware support #4206
• Netlify Edge Functions - Apparently based on Deno
• Fastly Compute@Edge
• AWS LLRT
• WinterJS

There are also other JS runtimes we can take a look at:

• Bun: Support for Bun #7979

Solution Brainstorm

If you are interested in this, please comment on the individual issues linked above!

[timfish]

It looks like there's talk of WinterCG TypeScript definitions but they don't appear to have been added. Having a lib.wintercg.d.ts in TypeScript would probably be a prerequisite to ensuring proper library compatibility.

I've not looked too deeply yet but running the code through deno bundle gives us a good idea of where there might be issues.
@sentry/core seems mostly compatible with WinterCG runtimes
@sentry/utils is where the issues lay

• instrument.ts contains a load of DOM/Browser types, XMLHttpRequest, Element, HTMLElement, etc
  • We probably need to pull browser specific instrumentation out of utils
• Various places accessing global, window, process can trip up type checking and bundlers and getGlobalObject is already getting pretty nuts:
  

  sentry-javascript/packages/utils/src/global.ts

  Lines 36 to 46 in 249e64d

  	export function getGlobalObject<T>(): T & SentryGlobal {
  	return (
  	isNodeEnv()
  	? global
  	: typeof window !== 'undefined' // eslint-disable-line no-restricted-globals
  	? window // eslint-disable-line no-restricted-globals
  	: typeof self !== 'undefined'
  	? self
  	: fallbackGlobalObject
  	) as T & SentryGlobal;
  	}

  • Should we pass the global object down from the Client to avoid error prone/bundler borking automatic detection?
• Should node.ts not be in @sentry/node rather than in utils?
  • We should try and remove the remaining usages of isNodeEnv and avoid all automatic platform detection entirely
• Same goes for browser.ts

That's all I've got for now!

[timfish]

The first step in supporting other runtimes is getting core, hub, types and utils compiling without dom/node types:

• - Move @sentry/hub code to @sentry/core and keep @sentry/hub as a stub re-exporting types from core so it's not a breaking change
  • ref(hub): Move @sentry/hub code to @sentry/core #5823
• - getGlobalObject should be replaced with something more universal like this from core-js. globalThis is the global in WinterCG and browsers/node have supported it for a while too
  • feat(utils): Modern implementation of getGlobalObject #5809
  • ref(utils): Remove getGlobalObject() usage from @sentry/utils #5831
  • ref(browser): Remove getGlobalObject() usage from @sentry/browser #5884
  • ref(tracing): Remove getGlobalObject() usage from @sentry/tracing  #5885
  • ref(core): Remove getGlobalObject() usage from @sentry/core #5914
  • ref(utils): Deprecate getGlobalObject as it's no longer used #5949
• - Remove DOM and node TypeScript lib types from packages that shouldn't be using them
  • Node types can be used in any package #5834
  • ref(typescript): Remove DOM from default lib types #5816

At this point, core, hub and types are compiling without DOM/node lib types.

However, utils still requires DOM and node lib types to build successfully.

To rectify this, all runtime specific code should be moved to the runtime packages:

• - Move all browser specific code from @sentry/utils to @sentry/browser/utils
  • - Move supportsErrorEvent, supportsDOMError, supportsDOMException, supportsFetch, supportsNativeFetch, supportsReferrerPolicy and supportsHistory to @sentry/browser
  • - Move some functions (like getLocationHref and getDomElement) from browser.ts to @sentry/browser
  • - Move everything in instrument.ts to @sentry/browser
    • ❌ This is an issue due to addInstrumentationHandler usage in tracing
• - Move all node specific code from @sentry/utils to @sentry/node
  • - Move everything in node.ts to @sentry/node
    • ❌ Moving dynamicRequire is an issue since it's used in tracing

The above can done without technically making breaking changes since we make no guarantees about @sentry/utils, but it will impact downstream SDKs that make use of some of the moved functions.

The major downside to moving these utilities to the browser/node packages and exporting them at the root is that they would become public API methods (for downstream SDKs to use) and with that comes stability guarantees.

It would be less of a maintenance headache to either:

• Move them to new packages (like @sentry/browser-utils) or package export (@sentry/browser/utils)
• Wrap them in an internal object export that we make no stability promises about

@sentry/tracing

There are a few issues above where @sentry/tracing relies on code from @sentry/utils which will get moved to browser/node. This will result in tracing depending on both browser/node. This can further be fixed by splitting the tracing code #5815.

[lforst]

How about having these as named exports? @sentry/tracing, @sentry/tracing/browser and @sentry/tracing/node?

Shouldn't it be @sentry/browser/tracing instead of @sentry/tracing/browser? So we can depend on @sentry/browser from within @sentry/browser/tracing. Maning the tracing submodule in @sentry/browser is just an extension of @sentry/browser. (I worded that kinda confusing but I think it gets the point across).

Also, I'd just have all tracing functionality in @sentry/node by default, so there wouldn't be any need for @sentry/node/tracing.

[timfish]

Yep, I need to update the above ramblings.

There's a more recent issue for the tracing changes.

Also, I'd just have all tracing functionality in @sentry/node by default, so there wouldn't be any need for @sentry/node/tracing.

Would we want to add all the hub extensions by default too?

We wouldn't want to run _autoloadDatabaseIntegrations in the Electron SDK because it hits app startup time significantly!

[lforst]

Continued thread over in more recent issue here: #5815 (comment)