Skip to content

docs(sentry-basics): Consolidate tutorials into one getting-started tutorial#18709

Open
coolguyzone wants to merge 21 commits into
masterfrom
Coolguyzone/feat/tutorial-update
Open

docs(sentry-basics): Consolidate tutorials into one getting-started tutorial#18709
coolguyzone wants to merge 21 commits into
masterfrom
Coolguyzone/feat/tutorial-update

Conversation

@coolguyzone

@coolguyzone coolguyzone commented Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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

@coolguyzone @claude
docs(sentry-basics): Consolidate tutorials into getting-started-tutorial
c0cc5fc 
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

vercel Bot commented Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
sentry-docs Ready Ready Preview Jul 23, 2026 7:01pm
1 Skipped Deployment
Project Deployment Actions Updated (UTC)
develop-docs Ignored Ignored Preview Jul 23, 2026 7:01pm

Request Review

@coolguyzone
coolguyzone marked this pull request as draft July 13, 2026 23:13
coolguyzone and others added 2 commits July 14, 2026 12:41
@coolguyzone @claude
docs(sentry-basics): Clarify source maps step for beginners
2cfa5aa 
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>
@coolguyzone @claude
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>
@coolguyzone @claude
docs(sentry-basics): Drop the GitHub/suspect-commits step
d3c9eeb 
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>
@coolguyzone @claude
docs(sentry-basics): Add step indicator + progress rail (frontend page)
a8102ab 
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>
@coolguyzone @claude
docs(sentry-basics): Roll out step counters + progress rails
98ba5e2 
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>
coolguyzone and others added 2 commits July 14, 2026 15:28
@coolguyzone @claude
docs(sentry-basics): Use non-checkable StepConnector rail
efd6c60 
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>
@coolguyzone @claude
docs(sentry-basics): Drop StepConnector, keep the step counter
2cea233 
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>
@coolguyzone @claude
docs(sentry-basics): Add tutorial progress bar with a bug marker
eb33138 
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>
coolguyzone and others added 4 commits July 14, 2026 15:54
@coolguyzone @claude
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>
@coolguyzone @claude
docs(sentry-basics): Squash the progress-bar bug on the final step
d1dee5e 
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>
@coolguyzone @claude
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>
@coolguyzone @claude
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>
@coolguyzone
coolguyzone requested a review from sfanahata July 15, 2026 18:43
sfanahata
sfanahata reviewed Jul 20, 2026
View reviewed changes
Comment thread docs/product/sentry-basics/getting-started-tutorial/index.mdx Outdated
sfanahata
sfanahata reviewed Jul 20, 2026
View reviewed changes
Comment thread docs/product/sentry-basics/getting-started-tutorial/create-new-project.mdx Outdated
sfanahata
sfanahata reviewed Jul 20, 2026
View reviewed changes
Comment thread docs/product/sentry-basics/getting-started-tutorial/create-new-project.mdx Outdated
sfanahata
sfanahata reviewed Jul 20, 2026
View reviewed changes
Comment thread docs/product/sentry-basics/getting-started-tutorial/create-new-project.mdx

@sfanahata sfanahata Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
sfanahata reviewed Jul 20, 2026
View reviewed changes
Comment thread docs/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-frontend.mdx
1. Clone the forked repository to your local environment:

```bash
git clone git@github.com:<your_username>/tracing-tutorial-frontend.git

@sfanahata sfanahata Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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" ?

@coolguyzone coolguyzone Jul 21, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch

sfanahata
sfanahata reviewed Jul 20, 2026
View reviewed changes
Comment thread docs/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-frontend.mdx Outdated
coolguyzone and others added 3 commits July 21, 2026 11:09
@coolguyzone @sfanahata
Update docs/product/sentry-basics/getting-started-tutorial/index.mdx
3c23d69 
Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>
@coolguyzone @sfanahata
Update docs/product/sentry-basics/getting-started-tutorial/create-new…
4c23c01 
…-project.mdx

Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>
@coolguyzone @sfanahata
Update docs/product/sentry-basics/getting-started-tutorial/initialize…
3b5e06e 
…-sentry-sdk-frontend.mdx

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

sfanahata commented Jul 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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

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
sfanahata reviewed Jul 21, 2026
View reviewed changes
Comment thread docs/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces.mdx

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:

@sfanahata sfanahata Jul 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Image

@coolguyzone coolguyzone Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is actually expected behavior, ORG_AUTH_TOKEN is actually a placeholder in docs and in production a signed-in user will see their actual org token, if you're not signed in it defaults to sntrys_YOUR_TOKEN_HERE. You can see how the behavior works in prod on https://docs.sentry.io/cli/configuration/

sfanahata
sfanahata reviewed Jul 21, 2026
View reviewed changes
Comment thread docs/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces.mdx Outdated
sfanahata
sfanahata reviewed Jul 21, 2026
View reviewed changes
Comment thread docs/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces.mdx
Comment on lines +128 to +132
2. Serve the production build:

```bash {tabTitle:npm}
npm run preview
```

@sfanahata sfanahata Jul 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@sfanahata sfanahata Jul 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@coolguyzone coolguyzone Jul 22, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perfect, ty!

@coolguyzone
coolguyzone marked this pull request as ready for review July 22, 2026 18:12
@coolguyzone @sfanahata
Update docs/product/sentry-basics/getting-started-tutorial/enable-rea…
985a4d9 
…dable-stack-traces.mdx

Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>
sentry[bot]
sentry Bot reviewed Jul 22, 2026
View reviewed changes
Comment thread src/components/featureInfo.tsx
coolguyzone and others added 2 commits July 22, 2026 11:51
@coolguyzone @claude
docs(sentry-basics): Load the backend SDK via node --import for ESM
5a723b3 
Load instrument.js with Node's --import flag instead of a top-of-file
import in server.js. A hoisted `import "./instrument.js"` in an ESM app
can let Express load before Sentry.init runs, making instrumentation
unreliable; --import guarantees the SDK initializes first.

- Drop the redundant `import "./instrument.js"` from the server.js diff
- Explain the --import start script and why ESM needs it

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@coolguyzone @claude
docs(sentry-basics): Offer HTTPS clone alternative on the backend page
0041a6c 
Show an HTTPS git clone command alongside the SSH one so readers without
SSH keys set up can still clone the sample backend.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@coolguyzone @claude
fix(featureInfo): Point Issues card at Issue Details docs
46b9912 
The consolidation left both the Issues and Tracing feature cards linking
to the same trace walkthrough. Point the Issues card at the Issue Details
documentation (viewing an error's full details) instead, so it no longer
sends users to a distributed-trace demo.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@coolguyzone @sfanahata
Update docs/product/sentry-basics/getting-started-tutorial/create-new…
9e2601c 
…-project.mdx

Co-authored-by: Shannon Anahata <shannon.anahata@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sfanahata sfanahata sfanahata left review comments
@sentry sentry[bot] sentry[bot] left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@coolguyzone @sfanahata