docs(sentry-basics): Consolidate tutorials into one getting-started tutorial by coolguyzone · Pull Request #18709 · getsentry/sentry-docs

coolguyzone · 2026-07-13T23:10:41Z

DESCRIBE YOUR PR

Consolidates the three overlapping, outdated Sentry Basics tutorials (distributed-tracing, integrate-frontend, integrate-backend) into a single, cohesive, JS-only getting-started tutorial: create projects → add the SDK to a React frontend and Express backend → capture a distributed-tracing error → (optionally) enable readable stack traces.

The two sample apps this tutorial uses were also refreshed in separate repos (Vite + React 19 frontend, ESM Express 5 backend, modernized storefront UI) and are already merged, so all in-doc repo links point at working code.

See https://sentry-docs-git-coolguyzone-feattutorial-update.sentry.dev/product/sentry-basics/getting-started-tutorial/

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

🤖 Generated with Claude Code

Merge the distributed-tracing, integrate-frontend, and integrate-backend tutorials into a single JS-only getting-started tutorial. The three overlapping tutorials were outdated and duplicated setup steps; this replaces them with one cohesive flow (React frontend + Express backend) covering project creation, SDK setup, distributed tracing, source maps, and suspect commits. - Add 7 pages under docs/product/sentry-basics/getting-started-tutorial/, with the source maps step updated for Vite and the backend for ESM - Delete the old integrate-frontend/ and integrate-backend/ tutorials - Add redirects from all old URLs to their new homes - Repoint inbound links across docs and featureInfo.tsx - Mark source maps and suspect commits as optional; add a ~60 min time estimate and a Seer entry in What's Next - Refresh Arcade IDs; hide outdated Arcades pending recapture Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel · 2026-07-13T23:10:47Z

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

Project	Deployment	Actions	Updated (UTC)
sentry-docs	Ready	Preview	Jul 21, 2026 6:21pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
develop-docs	Ignored	Preview	Jul 21, 2026 6:21pm

Make the "Enable Readable Stack Traces" page work for a new developer and fix the auth-token setup that didn't actually work with Vite. - Store the auth token in .env.sentry-build-plugin (the file the Sentry Vite plugin auto-loads) instead of a plain .env, which Vite does not load into process.env; drop the non-working authToken config line - Spell out how to find the org and project slugs in the Sentry UI - Warn that the source-map project must match the DSN's project - Add a screenshot of the readable frontend stack trace Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Replace the stale Create React App screenshot with the modernized storefront, and give the image descriptive alt text. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The suspect commits + stack trace linking step required installing the GitHub integration (which can need org-owner approval) plus a multi-part setup — too involved for a getting-started tutorial. Remove it as a hands-on step and surface the feature (and Seer) as "go further" links in the wrap-up instead. - Delete configure-suspect-commits.mdx (former step 6) - Move the What's Next wrap-up onto the source-maps page; add a suspect commits / GitHub integration link and reword the Seer entry - Update the step list, drop the suspect-commits capability bullet, and lower the time estimate to ~45 min - Repoint the integrate-frontend/configure-scms redirect to the GitHub integration docs Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add a "Step 2 of 5" orientation line and wrap the sub-steps in <StepConnector checkable> so readers can track completion. Applied to the frontend SDK page first to preview the look before rolling out. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Apply the "Step X of 5" indicator and <StepConnector checkable> rail to the remaining step pages (create-new-project, initialize-sentry-sdk-backend, generate-first-error, enable-readable-stack-traces) so all five steps have consistent progress affordances. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Switch the step pages from <StepConnector checkable> to the numbered, non-checkable form used by the platform onboarding pages. Drops the checkbox/Reset control that rendered without the accompanying rail. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The StepConnector rail didn't render its numbered circles on the tutorial pages (only the checkbox/reset control showed). Remove it from all step pages and keep the simple "Step X of 5" counter for orientation; restore the manual sub-step numbering on the section headings. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add a TutorialProgress component: a slim track that fills with Sentry purple in proportion to step/total, with a minimal purple bug icon riding the tip of the fill. Place it under the "Step X of 5" counter on each of the five step pages. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Cap the bar at ~1/3 of the content width and give the bug a bold dark outline (plus slightly thicker legs/antennae) so it stands out. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Render a flattened, legs-splayed "squashed" bug variant when step === total, so the bug that's been riding the progress bar gets squashed at the finish. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Replace the squashed-bug variant with a small purple headstone reading "RIP / BUGS" (two lines) shown when step === total. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Revert the final-step tombstone/squashed variant; the progress bar shows the upright bug at every step for now. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

sfanahata · 2026-07-20T23:00:12Z


 1. Log in to your [Sentry organization](https://sentry.io).

-1. Select **Projects** from the organization icon menu.
+1. Select **Projects** from the left side navigation menu.


Suggested change

1. Select **Projects** from the left side navigation menu.

1. Click on your organization's icon in the top left navigation, and select **Projects** from the menu.

sfanahata · 2026-07-20T23:09:10Z

I think this instruction is also handy above in the FE tutorial. It talks a good deal about the DSN, but not to copy it or keep it handy. I haven't used it yet in my setup, I've only created these two projects in Sentry.io.

sfanahata · 2026-07-20T23:30:09Z

+1. Clone the forked repository to your local environment:
+
+   ```bash
+   git clone git@github.com:<your_username>/tracing-tutorial-frontend.git


I didn't have SSH set up, so this failed. Maybe say, "if you already have SSH set up, use git clone git@github.com:<your_username>/tracing-tutorial-frontend.git

Otherwise use `git clone https://github.com/<your_username>/tracing-tutorial-frontend.git" ?

sfanahata · 2026-07-20T23:44:23Z

+1. Clone the forked repository to your local environment:
+
+   ```bash
+   git clone git@github.com:<your_username>/tracing-tutorial-backend.git


Same as in the FE. Maybe also suggest using git clone https://github.com/<your_username>/tracing-tutorial-backend.git in case SSH isn't set up.

Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>

…-project.mdx Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>

…-sentry-sdk-frontend.mdx Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>

sfanahata · 2026-07-21T18:59:14Z

@coolguyzone I think there might be a malformed part of the backend files.

I couldn't get Sentry to initialize the way it was set up, and this was the recommended change in package.json. Once I updated that, it worked, so I think that's the right move.

In package.json update to:

    "start": "node --import ./instrument.js server.js"
  },

I have a PR open for that change now.

sfanahata · 2026-07-21T19:09:19Z

+
+1. In the **root** of the `tracing-tutorial-frontend` folder (the same folder that contains `package.json`), create a new file named exactly `.env.sentry-build-plugin` — including the leading dot.
+
+1. Add your auth token to the file, replacing `___ORG_AUTH_TOKEN___` with the token you generated above:


For some reason, __ORG_AUTH_TOKEN__ is being replaced by SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE. I can see it flipping over when I refresh the page. Not sure what's going on there.

sfanahata · 2026-07-21T19:18:39Z

+   pnpm preview
+   ```
+
+3. Open the app (make sure the backend is still running on `http://localhost:3001`), open your browser's dev console, and perform an "Empty Cache and Hard Reload" so the new build is served. Then trigger the cross-project error again by clicking the **Nonfat Water** button.


Suggested change

3. Open the app (make sure the backend is still running on `http://localhost:3001`), open your browser's dev console, and perform an "Empty Cache and Hard Reload" so the new build is served. Then trigger the cross-project error again by clicking the **Nonfat Water** button.

3. Open the app (make sure the backend is still running on `http://localhost:3001`), open your browser's dev console, and right-click the reload button, then select 'Empty Cache and Hard Reload' so the new build is served. Then trigger the cross-project error again by clicking the **Nonfat Water** button.

sfanahata · 2026-07-21T19:21:03Z

+2. Serve the production build:
+
+   ```bash {tabTitle:npm}
+   npm run preview
+   ```


Looks like, by default, vite preview serves on port 4173. Should be noted.

Actually, just hardcoded the preview port too in a PR.

coolguyzone marked this pull request as draft July 13, 2026 23:13

vercel Bot deployed to Preview – develop-docs July 13, 2026 23:16 View deployment

vercel Bot deployed to Preview – sentry-docs July 13, 2026 23:24 View deployment

coolguyzone and others added 2 commits July 14, 2026 12:41

docs(sentry-basics): Update sample app screenshot to redesigned UI

1937e79

Replace the stale Create React App screenshot with the modernized storefront, and give the image descriptive alt text. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview – sentry-docs July 14, 2026 19:55 View deployment

vercel Bot deployed to Preview – develop-docs July 14, 2026 20:21 View deployment

vercel Bot deployed to Preview – sentry-docs July 14, 2026 20:29 View deployment

vercel Bot deployed to Preview – sentry-docs July 14, 2026 22:11 View deployment

vercel Bot deployed to Preview – sentry-docs July 14, 2026 22:25 View deployment

coolguyzone and others added 2 commits July 14, 2026 15:28

vercel Bot deployed to Preview – sentry-docs July 14, 2026 22:44 View deployment

vercel Bot deployed to Preview – develop-docs July 14, 2026 22:53 View deployment

coolguyzone and others added 4 commits July 14, 2026 15:54

docs(sentry-basics): Refine tutorial progress bar

af87682

Cap the bar at ~1/3 of the content width and give the bug a bold dark outline (plus slightly thicker legs/antennae) so it stands out. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(sentry-basics): Swap final-step bug for a RIP BUGS tombstone

f642bb3

Replace the squashed-bug variant with a small purple headstone reading "RIP / BUGS" (two lines) shown when step === total. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs(sentry-basics): Show the plain bug on all steps

9ad83ef

Revert the final-step tombstone/squashed variant; the progress bar shows the upright bug at every step for now. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview – develop-docs July 14, 2026 23:06 View deployment

vercel Bot deployed to Preview – sentry-docs July 14, 2026 23:13 View deployment

coolguyzone requested a review from sfanahata July 15, 2026 18:43

sfanahata reviewed Jul 20, 2026

View reviewed changes

Comment thread docs/product/sentry-basics/getting-started-tutorial/index.mdx Outdated

sfanahata reviewed Jul 20, 2026

View reviewed changes

Comment thread docs/product/sentry-basics/getting-started-tutorial/create-new-project.mdx Outdated

sfanahata reviewed Jul 20, 2026

View reviewed changes

Comment thread docs/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-frontend.mdx Outdated

sfanahata reviewed Jul 20, 2026

View reviewed changes

coolguyzone and others added 3 commits July 21, 2026 11:09

Update docs/product/sentry-basics/getting-started-tutorial/index.mdx

3c23d69

Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>

Update docs/product/sentry-basics/getting-started-tutorial/create-new…

4c23c01

…-project.mdx Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>

Update docs/product/sentry-basics/getting-started-tutorial/initialize…

3b5e06e

…-sentry-sdk-frontend.mdx Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>

vercel Bot deployed to Preview – sentry-docs July 21, 2026 18:21 View deployment

sfanahata reviewed Jul 21, 2026

View reviewed changes

	1. Select Projects from the left side navigation menu.
	1. Click on your organization's icon in the top left navigation, and select Projects from the menu.


		1. In the root of the `tracing-tutorial-frontend` folder (the same folder that contains `package.json`), create a new file named exactly `.env.sentry-build-plugin` — including the leading dot.

		1. Add your auth token to the file, replacing `___ORG_AUTH_TOKEN___` with the token you generated above:

	3. Open the app (make sure the backend is still running on `http://localhost:3001`), open your browser's dev console, and perform an "Empty Cache and Hard Reload" so the new build is served. Then trigger the cross-project error again by clicking the Nonfat Water button.
	3. Open the app (make sure the backend is still running on `http://localhost:3001`), open your browser's dev console, and right-click the reload button, then select 'Empty Cache and Hard Reload' so the new build is served. Then trigger the cross-project error again by clicking the Nonfat Water button.

Uh oh!

Uh oh!

Conversation

coolguyzone commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

DESCRIBE YOUR PR

IS YOUR CHANGE URGENT?

SLA

PRE-MERGE CHECKLIST

Uh oh!

vercel Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

Uh oh!

sfanahata commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sfanahata Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

coolguyzone commented Jul 13, 2026 •

edited

Loading

vercel Bot commented Jul 13, 2026 •

edited

Loading

sfanahata commented Jul 21, 2026 •

edited

Loading

sfanahata Jul 21, 2026 •

edited

Loading