Skip to content
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 60 additions & 2 deletions docs/platforms/javascript/guides/cloudflare/frameworks/nextjs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down
Loading