docs(cloudflare): Restructure the guide around the Vite setup - #19362
Open
JPeer264 wants to merge 1 commit into
Open
docs(cloudflare): Restructure the guide around the Vite setup#19362JPeer264 wants to merge 1 commit into
JPeer264 wants to merge 1 commit into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
the
Priority: Needs Triage
Contributor
|
Please update the IS YOUR CHANGE URGENT? section of the PR description:
This information helps the Docs team prioritize your review. |
JPeer264
added this pull request to stack #19363
September 11, 2026 08:46
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
JPeer264
force-pushed
the
janpeer/sdk-1426-cloudflare-getting-started-manual-setup-v10
branch
from
September 11, 2026 08:50
416a998 to
2bd9dce
Compare
Fixes what a new user hits between install and the first event, from the runtime docs audit (SDK-1426), and reorganizes the guide so the recommended Vite path leads. - Add the missing SDK import to the tracing verify snippets, which threw `ReferenceError: Sentry is not defined` when copied verbatim - Lead the quick start with the Vite plugin and an `instrument.server.ts` file, turning on the experimental `autoInstrumentation` and `useDiagnosticsChannelInjection` options - Add an Installation Methods section holding the Vite Plugin page, moved out of Features, and a new Wrangler page for the `withSentry` setup - Move the Cloudflare Pages setup to its own page, with a note recommending Workers with static assets - Move release detection and post-response spans to troubleshooting - Give the Hono framework page the real install and `app.use(sentry())` steps instead of a bare redirect - List the packages the plugin instruments at build time - Render `compatibility_date` from the build date with Cloudflare's "Set this to today's date" comment, instead of pinning the SDK minimum Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
JPeer264
force-pushed
the
janpeer/sdk-1426-cloudflare-getting-started-manual-setup-v10
branch
from
September 11, 2026 09:01
2bd9dce to
5e124f9
Compare
RulaKhaled
self-requested a review
September 11, 2026 09:14
coolguyzone
reviewed
Sep 14, 2026
|
|
||
| <Alert> | ||
|
|
||
| Cloudflare recommends [migrating to Workers with static assets](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/). Workers covers most Pages use cases with a broader feature set, and it's where new Cloudflare features land. Pages keeps working, so this page stays accurate, but start new projects on Workers and follow the <PlatformLink to="/">Cloudflare guide</PlatformLink> instead. |
Contributor
There was a problem hiding this comment.
Suggested change
| Cloudflare recommends [migrating to Workers with static assets](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/). Workers covers most Pages use cases with a broader feature set, and it's where new Cloudflare features land. Pages keeps working, so this page stays accurate, but start new projects on Workers and follow the <PlatformLink to="/">Cloudflare guide</PlatformLink> instead. | |
| Cloudflare recommends [migrating to Workers with static assets](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/). Workers covers most Pages use cases with a broader feature set, and it's where new Cloudflare features land. Existing Pages projects will continue to work, so the guidance on this page remains accurate. For new projects, however, use Workers and follow the <PlatformLink to="/">Cloudflare guide</PlatformLink> instead. |
coolguyzone
reviewed
Sep 14, 2026
|
|
||
| Cloudflare recommends [migrating to Workers with static assets](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/). Workers covers most Pages use cases with a broader feature set, and it's where new Cloudflare features land. Pages keeps working, so this page stays accurate, but start new projects on Workers and follow the <PlatformLink to="/">Cloudflare guide</PlatformLink> instead. | ||
|
|
||
| After migrating, you replace `sentryPagesPlugin` with the Vite plugin or `withSentry`, depending on how you build. |
Contributor
There was a problem hiding this comment.
Suggested change
| After migrating, you replace `sentryPagesPlugin` with the Vite plugin or `withSentry`, depending on how you build. | |
| After migrating, use the Vite plugin or `withSentry` instead of `sentryPagesPlugin`, depending on your build setup. |
coolguyzone
reviewed
Sep 14, 2026
|
|
||
| How you set the SDK up depends on how your Worker is built, not on which features you want. All methods give you the same errors, traces, and options. | ||
|
|
||
| ### I build my Worker with Vite |
Contributor
There was a problem hiding this comment.
Suggested change
| ### I build my Worker with Vite | |
| ### If You Build Your Worker With Vite |
coolguyzone
reviewed
Sep 14, 2026
|
|
||
| Follow the <PlatformLink to="/">quick start</PlatformLink>, which sets Sentry up this way. This is what we recommend: the <PlatformLink to="/install/vite-plugin/">Vite plugin</PlatformLink> wraps your Worker entry at build time, so you don't write the wrapper yourself, and it instruments bundled dependencies such as database clients, which is the only way to trace them in the Workers runtime. See the <PlatformLink to="/install/vite-plugin/">Vite Plugin</PlatformLink> page for its options and what it instruments. | ||
|
|
||
| ### I deploy with `wrangler` directly |
Contributor
There was a problem hiding this comment.
Suggested change
| ### I deploy with `wrangler` directly | |
| ### If You Deploy Directly With `wrangler` |
coolguyzone
reviewed
Sep 14, 2026
|
|
||
| Follow the <PlatformLink to="/install/wrangler/">Wrangler setup</PlatformLink> and wrap your entry with `Sentry.withSentry()` yourself. You keep errors and request traces, but you lose the build-time instrumentation of bundled dependencies, so spans from those packages won't appear. | ||
|
|
||
| ### I'm deploying a Cloudflare Pages application |
Contributor
There was a problem hiding this comment.
Suggested change
| ### I'm deploying a Cloudflare Pages application | |
| ### If You're Deploying a Cloudflare Pages Application |
coolguyzone
reviewed
Sep 14, 2026
| creating `instrument.server.ts`. This page documents what it instruments, its | ||
| options, and the details that matter once it's running. | ||
|
|
||
| ## Auto-instrumentation |
Contributor
There was a problem hiding this comment.
Suggested change
| ## Auto-instrumentation | |
| ## Auto-Instrumentation |
coolguyzone
reviewed
Sep 14, 2026
|
|
||
| The plugin reads your wrangler config (probing `wrangler.json`, `wrangler.jsonc`, and `wrangler.toml` at the Vite root, or the file set with [`wranglerConfigPath`](#wranglerconfigpath)) to find the entry point, Durable Objects, workflows, and Agents SDK classes. It wraps Agents SDK classes (`Agent`, `AIChatAgent`, `McpAgent`) with `instrumentAgentWithSentry`, which also gives them automatic conversation IDs (see <PlatformLink to="/agent-tracing/agents-sdk/">Cloudflare Agents SDK</PlatformLink>). | ||
|
|
||
| An entry you wrapped with `withSentry` yourself is left untouched, so manual instrumentation keeps working next to the plugin. If you'd rather wrap the entry yourself, leave `_experimental.autoInstrumentation` off and follow the <PlatformLink to="/install/wrangler/">Wrangler setup</PlatformLink>. |
Contributor
There was a problem hiding this comment.
Suggested change
| An entry you wrapped with `withSentry` yourself is left untouched, so manual instrumentation keeps working next to the plugin. If you'd rather wrap the entry yourself, leave `_experimental.autoInstrumentation` off and follow the <PlatformLink to="/install/wrangler/">Wrangler setup</PlatformLink>. | |
| Any entry you wrapped with `withSentry` yourself is left untouched, so manual instrumentation keeps working next to the plugin. If you'd rather wrap the entry yourself, leave `_experimental.autoInstrumentation` off and follow the <PlatformLink to="/install/wrangler/">Wrangler setup</PlatformLink>. |
coolguyzone
reviewed
Sep 14, 2026
|
|
||
| </Alert> | ||
|
|
||
| If you deploy with `wrangler` directly rather than building with Vite, wrap your Worker entry yourself with `Sentry.withSentry()`. |
Contributor
There was a problem hiding this comment.
Suggested change
| If you deploy with `wrangler` directly rather than building with Vite, wrap your Worker entry yourself with `Sentry.withSentry()`. | |
| If you deploy with `wrangler` directly rather than building with Vite, wrap your Worker entry manually with `Sentry.withSentry()`. |
coolguyzone
approved these changes
Sep 14, 2026
coolguyzone
left a comment
coolguyzone
left a comment
Contributor
There was a problem hiding this comment.
LGTM! Thanks for keeping this up to date!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
DESCRIBE YOUR PR
Fixes what a new user hits between install and the first event, from the runtime docs audit (SDK-1426), and reorganizes the guide so the recommended Vite path leads.
This can be merged already now as this just moves things around promoting the Vite plugin to ensure people have the best experience with the SDK
ReferenceError: Sentry is not definedwhen copied verbatiminstrument.server.tsfile, turning on the experimentalautoInstrumentationanduseDiagnosticsChannelInjectionoptionswithSentrysetupapp.use(sentry())steps instead of a bare redirectcompatibility_datefrom the build date with Cloudflare's "Set this to today's date" comment, instead of pinning the SDK minimumIS YOUR CHANGE URGENT?
Help us prioritize incoming PRs by letting us know when the change needs to go live.
Select exactly one option. For deadlines, replace
YYYY-MM-DDwith the due date. You can update this information later by editing the PR description.SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes:
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