From f3eaa76f45a5393ab7f2f74ce13517b3f11a16bf Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Wed, 23 Sep 2026 12:50:31 +0200 Subject: [PATCH 1/3] docs: Standardize internal package READMEs Co-Authored-By: GPT-6 --- packages/browser-utils/README.md | 11 +++++++---- packages/core/README.md | 16 ++++++++++------ packages/integration-shims/README.md | 16 ++++++++++++++-- packages/replay-worker/README.md | 16 +++++++++++++--- packages/server-runtime-injection/README.md | 18 +++++++++++++----- packages/server-utils/README.md | 12 +++++++----- packages/vercel-edge/README.md | 19 ++++++++++++------- 7 files changed, 76 insertions(+), 32 deletions(-) diff --git a/packages/browser-utils/README.md b/packages/browser-utils/README.md index 58b19de5d5a6..0e8f9a34a390 100644 --- a/packages/browser-utils/README.md +++ b/packages/browser-utils/README.md @@ -10,14 +10,17 @@ [![npm dm](https://img.shields.io/npm/dm/@sentry/browser-utils.svg)](https://www.npmjs.com/package/@sentry/browser-utils) [![npm dt](https://img.shields.io/npm/dt/@sentry/browser-utils.svg)](https://www.npmjs.com/package/@sentry/browser-utils) +Shared browser utilities used by Sentry’s JavaScript SDKs. + > [!NOTE] > This package is an internal library published for use by Sentry-owned JavaScript SDK packages. It is not part of the > public API contract and may change in any release. Do not rely on SemVer compatibility if you depend on it directly. -## Links +## Documentation -- [Official SDK Docs](https://docs.sentry.io/quickstart/) +- [JavaScript SDK documentation](https://docs.sentry.io/platforms/javascript/) -## General +## Support -Common utilities used by the Sentry JavaScript SDKs. +- [Report a bug](https://github.com/getsentry/sentry-javascript/issues/new/choose) +- [Contributing](https://github.com/getsentry/sentry-javascript/blob/develop/CONTRIBUTING.md) diff --git a/packages/core/README.md b/packages/core/README.md index c4c26b591b3e..6d01dfc2e29b 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -10,13 +10,17 @@ [![npm dm](https://img.shields.io/npm/dm/@sentry/core.svg)](https://www.npmjs.com/package/@sentry/core) [![npm dt](https://img.shields.io/npm/dt/@sentry/core.svg)](https://www.npmjs.com/package/@sentry/core) -## Links +Interface definitions, base classes, and utilities for building Sentry JavaScript SDKs. -- [Official SDK Docs](https://docs.sentry.io/quickstart/) +> [!NOTE] +> This package is an internal library published for use by Sentry-owned JavaScript SDK packages. It is not part of the +> public API contract and may change in any release. Do not rely on SemVer compatibility if you depend on it directly. -## General +## Documentation -This package contains interface definitions, base classes and utilities for building Sentry JavaScript SDKs, like -`@sentry/node` or `@sentry/browser`. +- [JavaScript SDK documentation](https://docs.sentry.io/platforms/javascript/) -Please consider all classes and exported functions and interfaces `internal`. +## Support + +- [Report a bug](https://github.com/getsentry/sentry-javascript/issues/new/choose) +- [Contributing](https://github.com/getsentry/sentry-javascript/blob/develop/CONTRIBUTING.md) diff --git a/packages/integration-shims/README.md b/packages/integration-shims/README.md index e315b1f61051..5a5d38f6f6f9 100644 --- a/packages/integration-shims/README.md +++ b/packages/integration-shims/README.md @@ -6,5 +6,17 @@ # Sentry Integration Shims -This internal package exports shims for Integrations, which are used in order to guarantee a consistent CDN bundle -output. +Integration shims used internally to ensure consistent Sentry CDN bundle output. + +> [!NOTE] +> This is a private package used internally by Sentry’s JavaScript SDKs. It is not part of the public API contract +> and may change at any time. + +## Documentation + +- [JavaScript SDK documentation](https://docs.sentry.io/platforms/javascript/) + +## Support + +- [Report a bug](https://github.com/getsentry/sentry-javascript/issues/new/choose) +- [Contributing](https://github.com/getsentry/sentry-javascript/blob/develop/CONTRIBUTING.md) diff --git a/packages/replay-worker/README.md b/packages/replay-worker/README.md index 9afc37e85b95..28a03abce79f 100644 --- a/packages/replay-worker/README.md +++ b/packages/replay-worker/README.md @@ -6,10 +6,11 @@ # Sentry Session Replay Worker -This is an internal package that is used by @sentry/replay. It generates a web worker and converts it to a -string, so that we can process it easier in replay. +Generates a web worker and converts it to a string for use by Sentry Session Replay. -By extracting this into a dedicated (private, internal) package, we can streamline the build of replay. +> [!NOTE] +> This is a private package used internally by Sentry’s JavaScript SDKs. It is not part of the public API contract +> and may change at any time. ## Example Worker @@ -17,3 +18,12 @@ You can find an example worker for if you want to self-host the compression work This is generated from the actual source via `yarn build:examples`, which should be run manually whenever replay-worker is updated. + +## Documentation + +- [Session Replay documentation](https://docs.sentry.io/platforms/javascript/session-replay/) + +## Support + +- [Report a bug](https://github.com/getsentry/sentry-javascript/issues/new/choose) +- [Contributing](https://github.com/getsentry/sentry-javascript/blob/develop/CONTRIBUTING.md) diff --git a/packages/server-runtime-injection/README.md b/packages/server-runtime-injection/README.md index e7c09f0935f0..59441bbbdf17 100644 --- a/packages/server-runtime-injection/README.md +++ b/packages/server-runtime-injection/README.md @@ -8,15 +8,23 @@ [![npm version](https://img.shields.io/npm/v/@sentry/server-runtime-injection.svg)](https://www.npmjs.com/package/@sentry/server-runtime-injection) -This is an internal package for the Sentry JavaScript SDKs. It is not part of the public API contract -and may change at any time. +Runtime module hooks and a code transformer that instrument dependencies as they load in Sentry’s server SDKs. -It contains the **runtime** diagnostics-channel injection used by the server SDKs — the module hooks -that transform instrumented dependencies as they load at runtime (`register`, `hook`, `import-hook`), -together with the vendored code transformer they rely on. +> [!NOTE] +> This package is an internal library published for use by Sentry-owned JavaScript SDK packages. It is not part of the +> public API contract and may change in any release. Do not rely on SemVer compatibility if you depend on it directly. > **Important:** this package must be kept **external** (not bundled) when bundling a server. Its > runtime hook loads a transformer that self-references its own on-disk `node_modules` location; > bundling it strips the transformer and breaks that self-reference. When you bundle your server, > either keep `@sentry/server-runtime-injection` external, or rely on the build-time instrumentation > from the Sentry bundler plugins instead. + +## Documentation + +- [JavaScript SDK documentation](https://docs.sentry.io/platforms/javascript/) + +## Support + +- [Report a bug](https://github.com/getsentry/sentry-javascript/issues/new/choose) +- [Contributing](https://github.com/getsentry/sentry-javascript/blob/develop/CONTRIBUTING.md) diff --git a/packages/server-utils/README.md b/packages/server-utils/README.md index 6cad314e2c62..913702972808 100644 --- a/packages/server-utils/README.md +++ b/packages/server-utils/README.md @@ -10,15 +10,17 @@ [![npm dm](https://img.shields.io/npm/dm/@sentry/server-utils.svg)](https://www.npmjs.com/package/@sentry/server-utils) [![npm dt](https://img.shields.io/npm/dt/@sentry/server-utils.svg)](https://www.npmjs.com/package/@sentry/server-utils) +Shared server-side utilities used by Sentry’s JavaScript SDKs. + > [!NOTE] > This package is an internal library published for use by Sentry-owned JavaScript SDK packages. It is not part of the > public API contract and may change in any release. Do not rely on SemVer compatibility if you depend on it directly. -## Links +## Documentation -- [Official SDK Docs](https://docs.sentry.io/quickstart/) +- [JavaScript SDK documentation](https://docs.sentry.io/platforms/javascript/) -## General +## Support -Common server-only utilities used by the Sentry JavaScript server SDKs (node, bun, deno, cloudflare, -aws-serverless, google-cloud-serverless, vercel-edge). +- [Report a bug](https://github.com/getsentry/sentry-javascript/issues/new/choose) +- [Contributing](https://github.com/getsentry/sentry-javascript/blob/develop/CONTRIBUTING.md) diff --git a/packages/vercel-edge/README.md b/packages/vercel-edge/README.md index 56a6ca051887..93abed231ea1 100644 --- a/packages/vercel-edge/README.md +++ b/packages/vercel-edge/README.md @@ -6,16 +6,21 @@ # Internal Sentry Utilities for Vercel Edge Runtime +[![npm version](https://img.shields.io/npm/v/@sentry/vercel-edge.svg)](https://www.npmjs.com/package/@sentry/vercel-edge) +[![npm dm](https://img.shields.io/npm/dm/@sentry/vercel-edge.svg)](https://www.npmjs.com/package/@sentry/vercel-edge) +[![npm dt](https://img.shields.io/npm/dt/@sentry/vercel-edge.svg)](https://www.npmjs.com/package/@sentry/vercel-edge) + +Vercel Edge Runtime utilities used by higher-level Sentry SDKs such as `@sentry/nextjs`. + > **NOTICE:** It is discouraged to depend on this package directly. `@sentry/vercel-edge` is used as building block for > higher level Sentry SDKs like `@sentry/nextjs`. The API of this `@sentry/vercel-edge` may break with any major and > non-major version! -[![npm version](https://img.shields.io/npm/v/@sentry/vercel-edge.svg)](https://www.npmjs.com/package/@sentry/vercel-edge) -[![npm dm](https://img.shields.io/npm/dm/@sentry/vercel-edge.svg)](https://www.npmjs.com/package/@sentry/vercel-edge) -[![npm dt](https://img.shields.io/npm/dt/@sentry/vercel-edge.svg)](https://www.npmjs.com/package/@sentry/vercel-edge) +## Documentation + +- [Next.js SDK documentation](https://docs.sentry.io/platforms/javascript/guides/nextjs/) -## Links +## Support -- [Sentry.io](https://sentry.io/?utm_source=github&utm_medium=npm_vercel_edge) -- [Sentry Discord Server](https://discord.gg/Ww9hbqr) -- [Stack Overflow](https://stackoverflow.com/questions/tagged/sentry) +- [Report a bug](https://github.com/getsentry/sentry-javascript/issues/new/choose) +- [Contributing](https://github.com/getsentry/sentry-javascript/blob/develop/CONTRIBUTING.md) From 4dece7d41565f4db2ed940d1488ebfdf51f95b49 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Wed, 23 Sep 2026 12:53:03 +0200 Subject: [PATCH 2/3] docs(replay-worker): Preserve package rationale Co-Authored-By: GPT-6 --- packages/replay-worker/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/replay-worker/README.md b/packages/replay-worker/README.md index 28a03abce79f..ca6e064e35b5 100644 --- a/packages/replay-worker/README.md +++ b/packages/replay-worker/README.md @@ -8,6 +8,8 @@ Generates a web worker and converts it to a string for use by Sentry Session Replay. +By extracting this into a dedicated (private, internal) package, we can streamline the build of replay. + > [!NOTE] > This is a private package used internally by Sentry’s JavaScript SDKs. It is not part of the public API contract > and may change at any time. From d4e2a9e944eae29dc155646e9d09ab27b9f48ad3 Mon Sep 17 00:00:00 2001 From: Nicolas Hrubec Date: Wed, 23 Sep 2026 12:55:48 +0200 Subject: [PATCH 3/3] docs: Clarify internal package purposes Co-Authored-By: GPT-6 --- packages/core/README.md | 5 ++--- packages/integration-shims/README.md | 2 +- packages/replay-worker/README.md | 2 +- packages/server-runtime-injection/README.md | 2 +- packages/vercel-edge/README.md | 2 +- 5 files changed, 6 insertions(+), 7 deletions(-) diff --git a/packages/core/README.md b/packages/core/README.md index 6d01dfc2e29b..8077bea4e165 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -10,11 +10,10 @@ [![npm dm](https://img.shields.io/npm/dm/@sentry/core.svg)](https://www.npmjs.com/package/@sentry/core) [![npm dt](https://img.shields.io/npm/dt/@sentry/core.svg)](https://www.npmjs.com/package/@sentry/core) -Interface definitions, base classes, and utilities for building Sentry JavaScript SDKs. +Shared foundations and utilities for Sentry’s JavaScript SDKs. > [!NOTE] -> This package is an internal library published for use by Sentry-owned JavaScript SDK packages. It is not part of the -> public API contract and may change in any release. Do not rely on SemVer compatibility if you depend on it directly. +> Please consider all classes and exported functions and interfaces `internal`. ## Documentation diff --git a/packages/integration-shims/README.md b/packages/integration-shims/README.md index 5a5d38f6f6f9..55cfd6b6a73c 100644 --- a/packages/integration-shims/README.md +++ b/packages/integration-shims/README.md @@ -6,7 +6,7 @@ # Sentry Integration Shims -Integration shims used internally to ensure consistent Sentry CDN bundle output. +Internal shims that provide consistent APIs across Sentry’s CDN bundles. > [!NOTE] > This is a private package used internally by Sentry’s JavaScript SDKs. It is not part of the public API contract diff --git a/packages/replay-worker/README.md b/packages/replay-worker/README.md index ca6e064e35b5..b201205667bc 100644 --- a/packages/replay-worker/README.md +++ b/packages/replay-worker/README.md @@ -6,7 +6,7 @@ # Sentry Session Replay Worker -Generates a web worker and converts it to a string for use by Sentry Session Replay. +Compression worker for Sentry Session Replay. By extracting this into a dedicated (private, internal) package, we can streamline the build of replay. diff --git a/packages/server-runtime-injection/README.md b/packages/server-runtime-injection/README.md index 59441bbbdf17..6ad8c1d61ac5 100644 --- a/packages/server-runtime-injection/README.md +++ b/packages/server-runtime-injection/README.md @@ -8,7 +8,7 @@ [![npm version](https://img.shields.io/npm/v/@sentry/server-runtime-injection.svg)](https://www.npmjs.com/package/@sentry/server-runtime-injection) -Runtime module hooks and a code transformer that instrument dependencies as they load in Sentry’s server SDKs. +Runtime instrumentation for Sentry’s JavaScript server SDKs. > [!NOTE] > This package is an internal library published for use by Sentry-owned JavaScript SDK packages. It is not part of the diff --git a/packages/vercel-edge/README.md b/packages/vercel-edge/README.md index 93abed231ea1..1929209d02d5 100644 --- a/packages/vercel-edge/README.md +++ b/packages/vercel-edge/README.md @@ -10,7 +10,7 @@ [![npm dm](https://img.shields.io/npm/dm/@sentry/vercel-edge.svg)](https://www.npmjs.com/package/@sentry/vercel-edge) [![npm dt](https://img.shields.io/npm/dt/@sentry/vercel-edge.svg)](https://www.npmjs.com/package/@sentry/vercel-edge) -Vercel Edge Runtime utilities used by higher-level Sentry SDKs such as `@sentry/nextjs`. +Internal Sentry SDK for the Vercel Edge Runtime. > **NOTICE:** It is discouraged to depend on this package directly. `@sentry/vercel-edge` is used as building block for > higher level Sentry SDKs like `@sentry/nextjs`. The API of this `@sentry/vercel-edge` may break with any major and