Skip to content

docs(js): Add a vinext guide with a sentry init quick start - #20875

Draft
JPeer264 wants to merge 1 commit into
masterfrom
jp/nextjs-vinext-quick-start
Draft

JPeer264 wants to merge 1 commit into
masterfrom
jp/nextjs-vinext-quick-start

Conversation

@JPeer264

Copy link
Copy Markdown
Member

DESCRIBE YOUR PR

Tell us what you're changing and why. If your PR resolves an issue, please link it so it closes automatically.

This adds a vinext guide at /platforms/javascript/guides/vinext/. The quick start uses sentry init. Manual Setup > Cloudflare has the manual steps (packages, Sentry Vite plugin, instrument.server.ts, onRequestError), checked against the vinext-cf-workers E2E app. The vinext parts move out of the Next.js on Cloudflare page, which now links to the new guide.

  • The Cloudflare framework selector lists vinext and links to its Cloudflare manual setup.
  • The shared pages that Cloudflare supports also show for vinext (javascript.vinext next to each javascript.cloudflare).
  • The quick start sidebar title names the runtime whenever the guide page sets runtime, so vinext shows "Quick Start (Cloudflare)". No other guide page sets runtime.

Tunneling decisions

The Tunneling page is hidden for vinext: its Cloudflare examples wrap a fetch handler with withSentry, which a vinext app does not have, and the guide has no browser setup. The alternative is a vinext section with instrument.server.ts examples.

Known issues

  • sentry init is not tested on vinext. The Sentry registry has no vinext entry, so it can set up the app as plain Next.js (withSentryConfig) instead of with the Vite plugin.
  • Code examples on the shared pages import from @sentry/cloudflare, not @sentry/nextjs/cloudflare.

IS 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-DD with the due date. You can update this information later by editing the PR description.

  • Urgent deadline (GA date, etc.): YYYY-MM-DD
  • Other deadline: YYYY-MM-DD
  • No deadline: 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 supplied a deadline.

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

Moves the vinext setup out of the Next.js on Cloudflare page into its own
guide. The quick start uses `sentry init`, and Manual Setup > Cloudflare has
the manual steps. The shared pages that Cloudflare supports also show for
vinext, except Tunneling.

The quick start sidebar title names the runtime whenever the guide page sets
`runtime`, so the vinext quick start shows "Quick Start (Cloudflare)".

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
develop-docs Ready Ready Preview Nov 18, 2026 11:24am UTC
sentry-docs Ready Ready Preview Nov 18, 2026 11:24am UTC

Request Review

@james-elicx james-elicx left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🤖 This review was generated and posted by AI (Claude), at the request of a vinext maintainer. It compares this guide against vinext's own code and the @sentry/[email protected] Vite plugin source. The findings come from reading that source; the documented flow wasn't run end to end.

You need:

- A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/)
- A vinext application that runs on Cloudflare Workers with the [Cloudflare Vite plugin](https://developers.cloudflare.com/workers/vite-plugin/)

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

This setup assumes a Wrangler-config project, but vinext init has scaffolded Cloudflare apps with cf + @cloudflare/vite-plugin@beta + cloudflare.config.ts by default since cloudflare/vinext#3504. Following this guide on those apps breaks in two ways:

  • @sentry/cloudflare/vite statically imports unstable_readConfig from wrangler, an optional peer. The cf setup doesn't install wrangler, so vite.config.ts fails to load with ERR_MODULE_NOT_FOUND.
  • With wrangler installed, the plugin still only probes wrangler.json, wrangler.jsonc and wrangler.toml in the Vite root. It logs "No parseable wrangler config found — auto-instrumentation disabled" and never wraps the entry.

Either state that this requires a Wrangler config (vinext init --legacy-wrangler-cloudflare-init), or have the plugin support cloudflare.config.ts.


### Add Your Sentry Options

Create an `instrument.server.ts` file next to your Worker entry, the file that `main` points at in your Wrangler configuration. If `main` is `worker/index.ts`, the file belongs at `worker/instrument.server.ts`, not at the project root.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

When main is a package path, the default vinext init writes when there's no worker/index.* ("main": "vinext/server/fetch-handler"), the plugin looks for instrument.server.* next to the Wrangler config, not next to the resolved entry. A file at worker/instrument.server.ts is never found. The Worker gets wrapped with () => undefined options, so it has no DSN and sends nothing.

Could this cover that case: "if main is vinext/server/fetch-handler, put it at the project root next to your Wrangler config"? The worker/instrument.server.ts filename in getting-started-data-collection/javascript.vinext.mdx has the same issue.

</PlatformSection>

<PlatformSection supported={["javascript.cloudflare"]}>
<PlatformSection supported={["javascript.cloudflare", "javascript.vinext"]}>

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

With vinext enabled here, vinext readers see src/instrument.server.ts importing from @sentry/cloudflare. The plugin never looks in src/ for a vinext app: it checks the project root (package main) or the entry's own directory (worker/). A user who creates the file as labelled gets an ignored options file. The vinext guide also imports defineCloudflareOptions from @sentry/nextjs/cloudflare, so the two pages disagree.

The same snippet appears at lines 142 and 194, in agent-tracing/index.mdx:172, and in troubleshooting/index.mdx:607.

title: vinext
description: "Learn how to set up Sentry in your vinext application on Cloudflare Workers and capture your first errors and traces."
sdk: sentry.javascript.nextjs
fallbackGuide: javascript.cloudflare

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

This fallback means every shared page without a vinext include renders the Cloudflare one. About 15 of those show src/instrument.server.ts, which has the same location problem as the logs page:

  • capture-console, dedupe, extra-error-data, feature flags, rewrite-frames
  • distributed tracing, logs setup, sample rate, traces sampler

A few others show a hand-written export default Sentry.withSentry(..., worker), which vinext apps don't have: stream mode, and the troubleshooting waitUntil example. Maybe add vinext variants of those includes, or a note that vinext's options file lives next to the Wrangler config or worker entry.

/>

<PlatformSection supported={["javascript.cloudflare"]}>
<PlatformSection supported={["javascript.cloudflare", "javascript.vinext"]}>

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

On vinext, these PlatformLinks resolve under /platforms/javascript/guides/vinext/…. Those pages only exist under guides/cloudflare/, so they're dead links:

  • /install/vite-plugin/: here (line 117), mcp-monitoring/index.mdx:61, postgresjs.mdx:18 and mistral.mdx:87
  • /agent-tracing/agents-sdk/: here and in mcp-monitoring
  • /install/wrangler/: here and in troubleshooting/index.mdx:616

PlatformLink only uses fallbackGuide for its support check, not for building the URL. The vinext guide itself links to the absolute Cloudflare URL, which works. The "If you deploy with wrangler directly" branches in these sections don't apply to vinext either.

sidebar_order: 10
supported:
- javascript.cloudflare
- javascript.vinext

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

This page says "For other build tools like Vite with Cloudflare, use the corresponding Vite guide", and vinext is a Vite build. Its flow doesn't match vinext: wrangler deploy --outdir dist re-bundling, and a hand-written Sentry.withSentry in index.ts in step 6. vinext deploys the Vite output (dist/server/wrangler.json), and the plugin already wraps the entry. Should vinext point to the Vite upload guide instead?

2. Build your app and run it in the Workers runtime on your machine:

```bash
npx vinext build && npx wrangler dev --config dist/server/wrangler.json

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

wrangler dev --config dist/server/wrangler.json only works for Wrangler-config projects. Apps scaffolded with the default cf setup don't have wrangler installed, and their generated preview script is vite preview. Worth showing both, or using npm run preview.

The test route is also app/… only; a Pages Router app would use pages/api/sentry-example-api.ts.

export default defineConfig({
plugins: [
vinext(),
cloudflare({ viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] } }),

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

The viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] } option is App Router only. Pages Router vinext apps use plain cloudflare(). Maybe add a note so Pages users don't copy the RSC config.

This branch was successfully deployed

2 active deployments
Preview – sentry-docs — 73620310 Deployed Nov 18, 2026 by vercel[bot]
Preview – develop-docs — 73620310 Deployed Nov 18, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Priority: Normal Docs review has no urgent deadline

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants