feat(nextjs) Update quickstart and manual setup

[sergical]

DESCRIBE YOUR PR

• Updates quickstart to add a checklist to verify setup
• Manual setup becomes more action driven with each step in the configuration / feature onboarding having it's own verification step

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.

• Urgent deadline (GA date, etc.):
• Other deadline:
• None: Not urgent, can wait up to 1 week+

SLA

• Teamwork makes the dream work, so please add a reviewer to your PRs.
• Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it.
  Thanks in advance for your help!

PRE-MERGE CHECKLIST

Make sure you've checked the following before merging your changes:

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

LEGAL BOILERPLATE

Look, I get it. The entity doing business as "Sentry" was incorporated in the State of Delaware in 2015 as Functional Software, Inc. and is gonna need some rights from me in order to utilize my contributions in this here PR. So here's the deal: I retain all rights, title and interest in and to my contributions, and by keeping this boilerplate intact I confirm that Sentry can use, modify, copy, and redistribute my contributions, under Sentry's choice of terms.

EXTRA RESOURCES

• Sentry Docs contributor guide

[linear]

DEVEX-149 Net New: Full getting started guide NextJS

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
develop-docs	Ready	Preview, Comment	Dec 17, 2025 7:37pm
sentry-docs	Ready	Preview, Comment	Dec 17, 2025 7:37pm

[codecov]

Bundle Report

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

Detailed changes

Bundle name	Size	Change
sentry-docs-server-cjs	24.83MB	108.94kB (0.44%) ⬆️
sentry-docs-client-array-push	10.23MB	-6 bytes (-0.0%) ⬇️

Affected Assets, Files, and Routes:

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	893.1kB	-0.0%
static/chunks/9366-*.js	-3 bytes	437.05kB	-0.0%
static/1Kt3svxY33Um5Qlrb_gLi/_buildManifest.js (New)	684 bytes	684 bytes	100.0% 🚀
static/1Kt3svxY33Um5Qlrb_gLi/_ssgManifest.js (New)	77 bytes	77 bytes	100.0% 🚀
static/AAlnv7xX4i2IPXZ7gIk8U/_buildManifest.js (Deleted)	-684 bytes	0 bytes	-100.0% 🗑️
static/AAlnv7xX4i2IPXZ7gIk8U/_ssgManifest.js (Deleted)	-77 bytes	0 bytes	-100.0% 🗑️

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

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
1729.js	-3 bytes	5.46MB	-0.0%
6529.js	-3 bytes	4.88MB	-0.0%
../instrumentation.js	-3 bytes	4.78MB	-0.0%
../app/[[...path]]/page.js.nft.json	36.32kB	1.11MB	3.38%
../app/platform-redirect/page.js.nft.json	36.32kB	1.11MB	3.38%
../app/sitemap.xml/route.js.nft.json	36.32kB	1.11MB	3.39%

[inventarSarah]

Hi @sergical!
First, thank you for working on this update. Nextjs is one of our more complex JS quick start guides -- i really appreciate the effort and thought you put into this. Below is my feedback, grouped by page so it's easier to follow.

Wizard

• I agree that we don't need to show configuration steps here since the wizard already handles that. I believe the config section ended up in this guide for testing purposes (could be wrong, though). We don't have them in our other guides.
• I like that the writing is tighter and in line with how we wanted the quick starts to be: focused with optional extra info via the Expandable components.
  • nit on the "What does the installation wizard do?" section: Your new version reads very cleanly, but we should make sure we provide valuable info and don't lose the context behind the changes. Users usually see which files changed via git, but they don't necessarily know what those changes mean
• I really like the idea of adding a bit of gamification to the verification step. This part (in the wizard) has always been tricky to handle because everything gets auto-set up and then users need to manually verify features. I get your intentions here :)
  My thoughts:
  • how does this work when users use the "copy page" button?
  • the links to Sentry (logs, traces, etc) are hidden by default
  • I love ticking off tasks but feel like the tasks here are very basic -- would devs actually come back here to tick boxes? (all in all there's a lot of clicking with not much outcome)
  • having users reselect features may add friction (this was added with the config earlier, not your change)
  • could be good to consider adding support options here? -- if a user can't check off an item because something didn't work, they're stuck with no troubleshooting path right there
• The sandbox warning is essential and should stay
• Turbopack info may also still be needed. Could you double-check with the devs if you haven't already?

Manual Setup

Like i wrote earlier, great job taking on this beast of a guide :D

A few notes:

• In general, the wizard and manual setup should lead to the same end result. Users shouldn't get "benefits" depending on which path they choose. I can't confirm this for your changes here, but just flagging it as context
• The current version of the guide was built together with the devs, and they have insight into why certain info is there; a lot of the content is very intentional. Checking with them early, especially when I was restructuring or removing things, was really helpful for me and saved me from cutting content that turned out to be more important than I expected. Just wanted to share that
• I like the idea of pairing config steps with their verification steps. It makes the flow feel much more actionable. I think we could improve this further
• Tunneling: do we need to add the "Using Next.js Middleware on Turbopack" expandable? Worth checking with the devs
• the manual setup page gets really long when all features are enabled. So adding a short intro explaining the structure (First we install and set up the basics; then we configure and verify each feature, ...) could help users orient themselves and prepare for what awaits them
• re the structure across the main page vs. Pages Router vs. Webpack:
  • The main manual guide tells users to check the other setup pages if they use Pages Router or Webpack. But those pages tell them to start with the main setup -> users may not know which steps apply to them and which don't. This could be confusing and makes it easy to misconfigure or double-configure.
  • After reviewing Pages Router more closely, I'm not sure it has enough unique content to justify a completely separate page. It may be better combined with the main guide, similar to how we currently have it. would love to know how the others think about this point!
  • Webpack page makes sense to me to keep separate if this is something fewer people use. Maybe create a complete setup guide so they can follow a guide from top to bottom.

Pages Router

• This page includes a "Hybrid apps" section (Pages + App Router), but the App Router guide doesn't. Is there a specific reason behind this?
• There's also a "Manually capture exceptions" section we only have on this page. Is there a specific reason behind this?

Webpack

• I like that you put everything Webpack-relevant here; looks good
• As mentioned above, it might help users if we expand this into a full setup guide

[coolguyzone]

Looks good!

[inventarSarah]

Thanks for the updates -- I really like this version! 💫

This is more a curiosity question than feedback: I was wondering what the reasoning was behind creating an almost complete Pages Router guide while leaving out things like the onboarding options.

[inventarSarah]

The hierarchy is a bit off (the content after ":" is not part of the list) -- I'd say either move "check your data" outside the list, maybe as a subheading.
Alternatively, we could include the content below in the list, but I don't think that would look good :D

[sergical]

idk i made it better or worse 😅

[inventarSarah]

If the user doesn't enable this feature, this step is missing and the guide is jumping from step 3 to step 5 (tracing)

[sergical]

yup, restructured to have the features all be part of the verify step, lmk what you think!

[inventarSarah]

Suggested change

	description: "Learn how to set up and configure Sentry in your Next.js application, capture your first errors, logs and traces and view them in Sentry"
	description: "Learn how to set up and configure Sentry in your Next.js application, capture your first errors, logs and traces and view them in Sentry."

[logaretm]

Great stuff here, I think this is great and really easy to follow without too much info overloading.

Just a quick note on tunnel configuration because I think it can be very confusing at its current state in the SDK and we could try to make it clear till we figure a way to solve it.

[logaretm]

medium: saw that we recommend fixed tunnel routes here but then recommend the true option in the webpack setup, is this intended?

I think we can stick to the fixed recommendation in all pages and mention the random tunnel generation in case the user wants to avoid adblockers, sadly the random tunnel option means the user has no way of excluding it in the middleware as we don't wrap it in turbopack builds and may stop doing it for webpack next major as well.

Lots of info 😅 here, I think we can just recommend the fixed one for now and mention the random tunnel option as a note or a comment.

cc @chargome

[sergical]

yeah, i updated to default to /monitoring and added an expandable on the webpack page to talk about dynamic tunneling, great catch!

[cursor]

Bug: Step toggle aria-label has off-by-one error

The aria-label for step toggle buttons uses stepNumber after it has been incremented on line 101, causing a mismatch between the displayed step number and the accessibility label. For numbered steps, a step with data-step="1" will have aria-label="Toggle completion for step 2". Additionally, for unnumbered steps (where noNumber is true), the aria-label still references a step number, which is semantically incorrect for steps without a number.

src/components/stepConnector/index.tsx#L108-L109

sentry-docs/src/components/stepConnector/index.tsx

Lines 108 to 109 in 678f185

	btn.className = styles.stepToggle;
	btn.setAttribute('aria-label', `Toggle completion for step ${stepNumber}`);

 

---