feat(js): Add SDK Options page by mydea · Pull Request #12502 · getsentry/sentry-docs

mydea · 2025-01-29T12:17:28Z

After talking some about this with @lforst and @Lms24, and triggered by talks with @inventarSarah, I decided to make a POC of a new SDK Options page for the JS SDKs.

This was borne out of the following thoughts:

Today, we have a page Configuration > Basic Options, which is a bit weird. First, it is pretty generic (originally applying to all SDKs, so containing a lot of generic language). Second, it is not fully up to date. And lastly, it is not really complete - some (many) options are described but not all.
It can be hard to actually find the available options.
It is hard for SDK maintainers to know where to document things.
The location/naming of this as "Configuration > Basic Options" is not super intutitive.

To improve on this, this PR introduces (for JS only, for now) a new top-level "SDK Options" nav item. This is a single page that contains all top-level SDK options that can be passed to Sentry.init(). There are a few goals here:

Make it complete - this should include all top-level options we want to document. Including replay, profiling, ... It does not literally have to be complete, we can choose to omit options we do not want to document.
Make it consistent - ensure all options have a consistent formatting, making it easy to read & author new options.
Add an index that can make it easier to scan this. Ideally, auto-generated.
Call out that certain options only apply to client/server SDKs

For this, I wrote two new components, a <SdkOption> component, and a <SdkOptionOverview> which just auto-generates an index for this. You can put headings and text between those for sectioning and explanation.

I also removed the old Basic options page as well as the transports page and folded that into the new page, adding redirects.

Some screenshots showing the different things:

Auto-generated Overview:

Option with env-var configuration:

Note that the env var entry will not be shown in environments where this is not auto-picked up.

Option with default value:

If in a meta-framework, options that are only available in one part or the other will be called out:

We can add more things to the SDK options if needed. The authoring experience with this should be pretty straightforward and make it easy to keep this up-to-date, hopefully.

Follow up

If this generally finds agreement, we can merge this. We should then make some passes over the actual options and make sure we add ones that have been forgotten, and/or improve docs on them where applicable. In some places, we have docs for options in more specific places, which should be folded into this page where possible.

When this is done, we would like to also add a top-level SDK APIs page, which does the same thing but for APIs, e.g. Sentry.captureException(), Sentry.setTag() etc. We can discuss this more separately.

The idea is that with these two pages, we'll be able to consolidate a good amount of the pages we currently have in various levels of nesting, and only keep additional pages for places where more explanation/examples are needed.

vercel · 2025-01-29T12:17:33Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
sentry-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Feb 5, 2025 11:30am

2 Skipped Deployments

Name	Status	Preview	Comments	Updated (UTC)
changelog	⬜️ Ignored (Inspect)	Visit Preview		Feb 5, 2025 11:30am
develop-docs	⬜️ Ignored (Inspect)	Visit Preview		Feb 5, 2025 11:30am

mydea · 2025-01-29T12:19:25Z

  children?: React.ReactNode;
  noGuides?: boolean;
-  notSupported?: string[];
+  notSupported?: `${PlatformCategory}`[];


Actually I wonder if we can remove that enum and just use string literals there overall, could not find a place where this was really used that way, but not sure... cc @chargome

Yeah getting rid of enums per se I think is a good idea, also could't spot anything where this would be actually used

I actually extracted this out a bit here: #12558

Lms24

I really like this rewrite! IMHO, this is much cleaner than the previous "Basic Options" page, both in description as well as UI. Love the table with the type and default value information.
I read through the options (haven't done this in a while) and had some minor suggestions. Once this is out of draft state, I'm happy to ✅ !

Lms24 · 2025-01-29T15:28:38Z

+
+</SdkOption>
+
+<SdkOption name="tracePropagationTargets" type='Array<string | RegExp>'>


I'd also add a default value entry into the table. Which needs to be different on browser and server.

yeah this is a bit tricky because 1. it is hard to implement this nicely (we can, if we want to) and especially 2. the default value here is not an actual value but computed (e.g. based on the current host), which is why I opted to rather explain the default in this case?

idea (logaf-l) should we then add something liks "see description" for the default value field?

chargome

Nice change!

chargome · 2025-01-29T18:16:00Z

+          </a>
+        </h3>
+
+        <table className="w-auto">


WDYT about wrapping this table with a border radius? (same value as the alert)

I updated it, it's a bit tricky because apparently border-collapse and border-radius do not like each other 😬 I ended up making the border 2px, which seems ok to me, but... 🤷

Hmm tricky, the prose class also makes this harder. Looks better with 1px imo and we need to adapt it to dark mode – I can do that tomorrow if you want!

some more hacking around, figured out a way to make 1px borders work!

chargome · 2025-01-29T18:20:21Z

  children?: React.ReactNode;
  noGuides?: boolean;
-  notSupported?: string[];
+  notSupported?: `${PlatformCategory}`[];


Yeah getting rid of enums per se I think is a good idea, also could't spot anything where this would be actually used

inventarSarah · 2025-01-30T10:00:42Z

That looks much clearer!
How are these options currently sorted? Would it make sense to sort them alphabetically to make them easier to find?

mydea · 2025-01-30T13:19:58Z

That looks much clearer! How are these options currently sorted? Would it make sense to sort them alphabetically to make them easier to find?

I've thought about this too some, IMHO it makes sense to have them manually sorted - right now it is just the order that you put them into the mdx file! Once we have general agreement on the direction etc. I would take some time to reorder these better, for now I mostly just cobbled it together in the order it already was in basic options.

codecov · 2025-01-31T08:44:12Z

Bundle Report

Changes will increase total bundle size by 7.67kB (0.04%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
sentry-docs-server-cjs	10.7MB	4.19kB (0.04%) ⬆️
sentry-docs-client-array-push	9.38MB	3.48kB (0.04%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: sentry-docs-server-cjs

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`1729.js`	-3 bytes	1.63MB	-0.0%
`../instrumentation.js`	-3 bytes	965.23kB	-0.0%
`9523.js`	-3 bytes	941.45kB	-0.0%
`../app/[[...path]]/page.js`	4.37kB	529.59kB	0.83%
`../app/[[...path]]/page.js.nft.json`	-78 bytes	375.92kB	-0.02%
`../app/platform-redirect/page.js.nft.json`	-78 bytes	375.84kB	-0.02%
`../app/sitemap.xml/route.js.nft.json`	-78 bytes	373.81kB	-0.02%
`2065.js` (New)	81.44kB	81.44kB	100.0% 🚀
`../app/platform-redirect/page.js`	2 bytes	30.83kB	0.01%
~~`3845.js`~~ (Deleted)	-81.39kB	0 bytes	-100.0% 🗑️

Files in ../app/[[...path]]/page.js:

./src/mdxComponents.ts → Total Size: 3.54kB
./src/components/tableOfContents.tsx → Total Size: 2.89kB
./src/components/sdkOption/style.module.scss → Total Size: 86 bytes
./src/components/tableOfContents.tsx → Total Size: 479 bytes
./src/components/sdkOption/index.tsx → Total Size: 8.43kB
./src/components/platformCategorySection.tsx → Total Size: 1.06kB

Files in 2065.js:

./src/components/sidebarTableOfContents/style.module.scss → Total Size: 268 bytes
./src/components/sidebarTableOfContents/index.tsx → Total Size: 520 bytes
./src/components/sidebarTableOfContents/index.tsx → Total Size: 5.23kB
./src/components/docPage/type.scss → Total Size: 1 bytes
./src/components/docPage/index.tsx → Total Size: 8.77kB

App Routes Affected:

App Route	Size Change	Total Size	Change (%)
/[[...path]]	4.37kB	3.08MB	0.14%
/platform-redirect	2 bytes	2.58MB	0.0%

view changes for bundle: sentry-docs-client-array-push

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`static/chunks/pages/_app-*.js`	-3 bytes	866.04kB	-0.0%
`static/css/*.css`	5.75kB	22.76kB	33.77% ⚠️
`static/css/*.css`	2.59kB	6.54kB	65.54% ⚠️
`static/css/*.css`	-7.52kB	8.57kB	-46.73%
`static/chunks/9557-*.js`	-3 bytes	391.11kB	-0.0%
`server/app/_not-*.js`	481 bytes	252.08kB	0.19%
`server/app/[[...path]]/page_client-*.js`	481 bytes	252.04kB	0.19%
`server/app/platform-*.js`	481 bytes	237.37kB	0.2%
`static/chunks/app/[[...path]]/page-*.js`	1.22kB	72.41kB	1.71%
*`static/chunks/818-.js`** (New)	41.51kB	41.51kB	100.0% 🚀
`static/chunks/app/platform-*.js`	-1 bytes	12.89kB	-0.01%
`app-*.json`	-2 bytes	4.18kB	-0.05%
`static/1kyi_2LsGAboYqBDpC2GN/_buildManifest.js` (New)	578 bytes	578 bytes	100.0% 🚀
`static/1kyi_2LsGAboYqBDpC2GN/_ssgManifest.js` (New)	77 bytes	77 bytes	100.0% 🚀
~~*`static/chunks/3920-.js`*~~ (Deleted)*	-41.5kB	0 bytes	-100.0% 🗑️
~~`static/yQisTFHL2fFEoitC_2EX3/_buildManifest.js`~~ (Deleted)	-578 bytes	0 bytes	-100.0% 🗑️
~~`static/yQisTFHL2fFEoitC_2EX3/_ssgManifest.js`~~ (Deleted)	-77 bytes	0 bytes	-100.0% 🗑️

Files in static/chunks/app/[[...path]]/page-*.js:

./src/components/tableOfContents.tsx → Total Size: 3.12kB
./src/components/sdkOption/style.module.scss → Total Size: 110 bytes

Files in static/chunks/818-*.js:

./src/components/docPage/type.scss → Total Size: 39 bytes
./src/components/sidebarTableOfContents/index.tsx → Total Size: 5.55kB
./src/components/sidebarTableOfContents/style.module.scss → Total Size: 277 bytes

mydea · 2025-02-04T13:52:47Z

I think this is ready for review now, I tried to address the things that have already been brought up. The options list itself for sure can use some more iteration and work, but IMHO we can do that step by step then too.

coolguyzone

Thanks @mydea! I don't see any issues here, however since a lot of these changes are on the more technical side, please also make sure a docs engineer approves as well before merging.

chargome

Thanks for the update, let's ship it and maybe check if can render the ToC during build time in a follow up PR 👍

Co-authored-by: Charly Gomez <charly.gomez@sentry.io>

Co-authored-by: Lukas Stracke <lukas.stracke@sentry.io>

Co-authored-by: Charly Gomez <charly.gomez@sentry.io>

mydea · 2025-02-05T11:16:23Z

after talking with @stephanie-anderson , for now we leave it under configuration > options!

mydea self-assigned this Jan 29, 2025

mydea commented Jan 29, 2025

View reviewed changes

vercel Bot deployed to Preview – develop-docs January 29, 2025 12:25 View deployment

vercel Bot deployed to Preview – sentry-docs January 29, 2025 12:36 View deployment

mydea force-pushed the fn/js-sdk-options branch from 7dc93a6 to 9cbb304 Compare January 29, 2025 13:14

vercel Bot deployed to Preview – develop-docs January 29, 2025 13:21 View deployment

vercel Bot deployed to Preview – develop-docs January 29, 2025 13:46 View deployment

vercel Bot deployed to Preview – sentry-docs January 29, 2025 13:56 View deployment

Lms24 reviewed Jan 29, 2025

View reviewed changes

chargome reviewed Jan 29, 2025

View reviewed changes

vercel Bot deployed to Preview – develop-docs January 30, 2025 15:01 View deployment

vercel Bot deployed to Preview – sentry-docs January 30, 2025 15:08 View deployment

vercel Bot deployed to Preview – develop-docs January 31, 2025 08:52 View deployment

vercel Bot deployed to Preview – sentry-docs January 31, 2025 09:08 View deployment

vercel Bot deployed to Preview – sentry-docs January 31, 2025 09:45 View deployment

mydea force-pushed the fn/js-sdk-options branch from b75d0b6 to fdbd537 Compare February 4, 2025 13:37

mydea marked this pull request as ready for review February 4, 2025 13:37

mydea requested review from a team and stephanie-anderson February 4, 2025 13:37

vercel Bot deployed to Preview – sentry-docs February 4, 2025 13:51 View deployment

chargome reviewed Feb 4, 2025

View reviewed changes

Comment thread src/components/sdkOption/index.tsx Outdated

coolguyzone approved these changes Feb 4, 2025

View reviewed changes

vercel Bot deployed to Preview – develop-docs February 5, 2025 07:58 View deployment

vercel Bot deployed to Preview – sentry-docs February 5, 2025 08:04 View deployment

chargome approved these changes Feb 5, 2025

View reviewed changes

mydea and others added 16 commits February 5, 2025 11:07

small fixes

b1b2467

[getsentry/action-github-commit] Auto commit

f3aed85

fix link

8d2eea4

fix links ??

c1c343e

Apply suggestions from code review

4cb54cc

Co-authored-by: Charly Gomez <charly.gomez@sentry.io>

make it more generic

75d67f4

improve style of table

d480f1e

move to redirects

89a36af

fix table border

87d2211

not needed anymore

bff9aaf

Apply suggestions from code review

09e9e08

Co-authored-by: Lukas Stracke <lukas.stracke@sentry.io>

small pr feedback

65f071a

fix more

03f2211

rename & small fixes

90fb18e

Apply suggestions from code review

cf1a874

Co-authored-by: Charly Gomez <charly.gomez@sentry.io>

pr fixes

0492f97

mydea force-pushed the fn/js-sdk-options branch from 28ec6e3 to 0492f97 Compare February 5, 2025 10:10

vercel Bot deployed to Preview – develop-docs February 5, 2025 10:17 View deployment

vercel Bot deployed to Preview – sentry-docs February 5, 2025 10:24 View deployment

mydea added 3 commits February 5, 2025 11:34

move it back?

ea212fc

reorder stuff

25f0f3d

fixes

297b7b6

stephanie-anderson approved these changes Feb 5, 2025

View reviewed changes

vercel Bot deployed to Preview – sentry-docs February 5, 2025 11:11 View deployment

small refs

31537be

vercel Bot deployed to Preview – sentry-docs February 5, 2025 11:30 View deployment

mydea merged commit d43e215 into master Feb 5, 2025

mydea deleted the fn/js-sdk-options branch February 5, 2025 11:49

github-actions Bot locked and limited conversation to collaborators Feb 21, 2025


		</SdkOption>

		<SdkOption name="tracePropagationTargets" type='Array<string \| RegExp>'>

Uh oh!

Conversation

mydea commented Jan 29, 2025

Follow up

Uh oh!

vercel Bot commented Jan 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Lms24 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chargome left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

inventarSarah commented Jan 30, 2025

Uh oh!

mydea commented Jan 30, 2025

Uh oh!

codecov Bot commented Jan 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Report

Affected Assets, Files, and Routes:

Assets Changed:

App Routes Affected:

Assets Changed:

Uh oh!

mydea commented Feb 4, 2025

Uh oh!

Uh oh!

coolguyzone left a comment

Choose a reason for hiding this comment

Uh oh!

chargome left a comment

Choose a reason for hiding this comment

Uh oh!

mydea commented Feb 5, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

vercel Bot commented Jan 29, 2025 •

edited

Loading

codecov Bot commented Jan 31, 2025 •

edited

Loading