From 0738dc894bfe5121fd3366f481ac4efb76a55ca5 Mon Sep 17 00:00:00 2001
From: "sentry-junior[bot]"
 <264270552+sentry-junior[bot]@users.noreply.github.com>
Date: Wed, 21 Oct 2026 09:30:58 +0000
Subject: [PATCH] docs(cloudflare): Document the vinext Worker entry wrapping
 of the Vite plugin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Jan VamPeer Stöcklmair <jan.peer@sentry.io>
---
 .../guides/cloudflare/frameworks/nextjs.mdx   | 62 ++++++++++++++++++-
 1 file changed, 60 insertions(+), 2 deletions(-)

diff --git a/docs/platforms/javascript/guides/cloudflare/frameworks/nextjs.mdx b/docs/platforms/javascript/guides/cloudflare/frameworks/nextjs.mdx
index 153052f73f9bd..15d706b118c3e 100644
--- a/docs/platforms/javascript/guides/cloudflare/frameworks/nextjs.mdx
+++ b/docs/platforms/javascript/guides/cloudflare/frameworks/nextjs.mdx
@@ -11,7 +11,7 @@ Before you begin, make sure you have:
 
 - A Sentry [account](https://sentry.io/signup/) and [project](/product/projects/)
 - A [Cloudflare Workers project](https://dash.cloudflare.com/workers/overview)
-- A Next.js application configured for Cloudflare Workers with [OpenNext](https://opennext.js.org/cloudflare)
+- A Next.js application configured for Cloudflare Workers with [OpenNext](https://opennext.js.org/cloudflare) or [vinext](https://github.com/cloudflare/vinext)
 - The Sentry SDK [installed and configured](/platforms/javascript/guides/nextjs/) in your Next.js application
 
 <Alert level="info">
@@ -57,6 +57,8 @@ compatibility_date = "2025-08-16"
 
 <AvailableSince version="11.6.0" />
 
+If you build your app with vinext, skip to [Wrap the Worker Entry With vinext](#wrap-the-worker-entry-with-vinext).
+
 On Cloudflare Workers, your Next.js app runs inside the Worker entry that OpenNext generates (`.open-next/worker.js`). Wrap this entry with `withSentry` from `@sentry/nextjs/cloudflare` to get the same Next.js spans as on Node.js, plus Cloudflare data such as spans for D1 queries. Each request gets one `http.server` span with the name of the Next.js route, and the Next.js spans become its children.
 
 `@sentry/nextjs` depends on `@sentry/cloudflare`, so you don't need to install another package.
@@ -97,9 +99,65 @@ Then, point `main` in your Wrangler configuration to this file:
 main = "./worker.ts"
 ```
 
+### Wrap the Worker Entry With vinext
+
+<AvailableSince version="11.6.0" />
+
+[vinext](https://github.com/cloudflare/vinext) builds your Next.js app with Vite, so you don't need a custom Worker. Add `sentryCloudflareVitePlugin` from `@sentry/cloudflare/vite` to your Vite config, and the plugin wraps your Worker entry with `withSentry` from `@sentry/nextjs/cloudflare` at build time. Your app gets the same Next.js spans as with OpenNext.
+
+The plugin uses `@sentry/nextjs/cloudflare` only when the build uses vinext and `@sentry/nextjs` is installed in version 11.6.0 or later. Otherwise, it wraps the entry with `withSentry` from `@sentry/cloudflare`, which sends no Next.js spans.
+
+Install `@sentry/cloudflare`, because you import the Vite plugin from it directly:
+
+```bash {tabTitle:npm}
+npm install @sentry/cloudflare
+```
+
+```bash {tabTitle:yarn}
+yarn add @sentry/cloudflare
+```
+
+```bash {tabTitle:pnpm}
+pnpm add @sentry/cloudflare
+```
+
+Then, add the plugin after the vinext and Cloudflare plugins:
+
+```typescript {filename:vite.config.ts}
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { sentryCloudflareVitePlugin } from "@sentry/cloudflare/vite";
+import vinext from "vinext";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    vinext(),
+    cloudflare({ viteEnvironment: { name: "rsc", childEnvironments: ["ssr"] } }),
+    sentryCloudflareVitePlugin(),
+  ],
+});
+```
+
+Pass your Sentry options in an `instrument.server.ts` file next to the Worker entry that `main` in your Wrangler configuration points to. For example, if `main` is `./worker/index.ts`, create `worker/instrument.server.ts`:
+
+```typescript {filename:worker/instrument.server.ts}
+import { defineCloudflareOptions } from "@sentry/nextjs/cloudflare";
+
+export default defineCloudflareOptions({
+  dsn: "___PUBLIC_DSN___",
+
+  // Set tracesSampleRate to 1.0 to capture 100% of spans for tracing.
+  // Learn more at
+  // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#tracesSampleRate
+  tracesSampleRate: 1.0,
+});
+```
+
+Without this file, the SDK reads its options, such as `SENTRY_DSN`, from the `env` bindings of the Worker. For more on the plugin, see the <PlatformLink to="/install/vite-plugin/">Vite plugin</PlatformLink> page.
+
 ### Server and Edge Configuration in the Worker
 
-In the Worker, `withSentry` creates the Sentry client. `Sentry.init()` in `sentry.server.config.ts` and `sentry.edge.config.ts` still runs, but it creates no client and only applies the `release` option. Set all other options in `withSentry`.
+In the Worker, `withSentry` creates the Sentry client. With vinext, the options of `withSentry` come from `instrument.server.ts`. `Sentry.init()` in `sentry.server.config.ts` and `sentry.edge.config.ts` still runs, but it creates no client and only applies the `release` option. Set all other options in `withSentry`.
 
 On Workers, these two files are optional. Keep them if you use `next dev`, which runs on Node.js and doesn't use the Worker entry. They also pass on the release that `withSentryConfig` sets at build time.