Skip to content

docs(cloudflare): Point README to SDK documentation #24624

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nicohrubec merged 1 commit into from
Sep 23, 2026
Merged

docs(cloudflare): Point README to SDK documentation #24624

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
208 changes: 8 additions & 200 deletions packages/cloudflare/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,207 +10,15 @@
[![npm dm](https://img.shields.io/npm/dm/@sentry/cloudflare.svg)](https://www.npmjs.com/package/@sentry/cloudflare)
[![npm dt](https://img.shields.io/npm/dt/@sentry/cloudflare.svg)](https://www.npmjs.com/package/@sentry/cloudflare)

## Links
The official Sentry SDK for monitoring Cloudflare applications.

- [Official SDK Docs](https://docs.sentry.io/quickstart/)
## Documentation

## Install
- [Getting started](https://docs.sentry.io/platforms/javascript/guides/cloudflare/)
- [Configuration](https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/)
- [Cloudflare-specific features](https://docs.sentry.io/platforms/javascript/guides/cloudflare/features/)

To get started, first install the `@sentry/cloudflare` package:
## Support

```bash
npm install @sentry/cloudflare
```

Then set the `nodejs_compat` compatibility flag in your `wrangler.jsonc`/`wrangler.toml` config. This is because the SDK needs access to Node.js compatibility APIs to work correctly.

```jsonc {tabTitle:JSON} {filename:wrangler.jsonc}
{
"compatibility_flags": ["nodejs_compat"],
}
```

```toml {tabTitle:Toml} {filename:wrangler.toml}
compatibility_flags = ["nodejs_compat"]
```

## Setup (Cloudflare Pages)

To use this SDK, add the `sentryPagesPlugin` as
[middleware to your Cloudflare Pages application](https://developers.cloudflare.com/pages/functions/middleware/).

We recommend adding a `functions/_middleware.js` for the middleware setup so that Sentry is initialized for your entire
app.

```javascript
// functions/_middleware.js
import * as Sentry from '@sentry/cloudflare';

export const onRequest = Sentry.sentryPagesPlugin({
dsn: process.env.SENTRY_DSN,
// Set tracesSampleRate to 1.0 to capture 100% of spans for tracing.
tracesSampleRate: 1.0,
});
```

If you need to to chain multiple middlewares, you can do so by exporting an array of middlewares. Make sure the Sentry
middleware is the first one in the array.

```javascript
import * as Sentry from '@sentry/cloudflare';

export const onRequest = [
// Make sure Sentry is the first middleware
Sentry.sentryPagesPlugin({
dsn: process.env.SENTRY_DSN,
tracesSampleRate: 1.0,
}),
// Add more middlewares here
];
```

If you need to access the `context` object (for example to grab environmental variables), you can pass a function to
`sentryPagesPlugin` that takes the `context` object as an argument and returns `init` options:

```javascript
export const onRequest = Sentry.sentryPagesPlugin(context => ({
dsn: context.env.SENTRY_DSN,
tracesSampleRate: 1.0,
}));
```

If you do not have access to the `onRequest` middleware API, you can use the `wrapRequestHandler` API instead.

Here is an example with SvelteKit:

```javascript
// hooks.server.js
import * as Sentry from '@sentry/cloudflare';

export const handle = ({ event, resolve }) => {
const requestHandlerOptions = {
options: {
dsn: event.platform.env.SENTRY_DSN,
tracesSampleRate: 1.0,
},
request: event.request,
context: event.platform.ctx,
};
return Sentry.wrapRequestHandler(requestHandlerOptions, () => resolve(event));
};
```

## Setup (Cloudflare Workers)

To use this SDK, wrap your handler with the `withSentry` function. This will initialize the SDK and hook into the
environment. Note that you can turn off almost all side effects using the respective options.

Currently only ESM handlers are supported.

```javascript
import * as Sentry from '@sentry/cloudflare';

export default withSentry(
env => ({
dsn: env.SENTRY_DSN,
// Set tracesSampleRate to 1.0 to capture 100% of spans for tracing.
tracesSampleRate: 1.0,
}),
{
async fetch(request, env, ctx) {
return new Response('Hello World!');
},
} satisfies ExportedHandler<Env>,
);
```

### Sourcemaps

Configure uploading sourcemaps via the Sentry Wizard:

```bash
npx @sentry/wizard@latest -i sourcemaps
```

See more details in our [docs](https://docs.sentry.io/platforms/javascript/sourcemaps/).

## Usage

To set context information or send manual events, use the exported functions of `@sentry/cloudflare`. Note that these
functions will require the usage of the Sentry helpers, either `withSentry` function for Cloudflare Workers or the
`sentryPagesPlugin` middleware for Cloudflare Pages.

```javascript
import * as Sentry from '@sentry/cloudflare';

// Set user information, as well as tags and further extras
Sentry.setExtra('battery', 0.7);
Sentry.setTag('user_mode', 'admin');
Sentry.setUser({ id: '4711' });

// Add a breadcrumb for future events
Sentry.addBreadcrumb({
message: 'My Breadcrumb',
// ...
});

// Capture exceptions, messages or manual events
Sentry.captureMessage('Hello, world!');
Sentry.captureException(new Error('Good bye'));
Sentry.captureEvent({
message: 'Manual',
stacktrace: [
// ...
],
});
```

## Cloudflare D1 Instrumentation

`withSentry()` automatically instruments all [Cloudflare D1](https://developers.cloudflare.com/d1/) bindings on `env`,
Cloudflare's serverless SQL database. Just use the binding as usual:

```javascript
// env.DB is the D1 DB binding configured in your `wrangler.toml`
await env.DB.prepare('SELECT * FROM table WHERE id = ?').bind(1).run();
```

## Cron Monitoring (Cloudflare Workers)

[Sentry Crons](https://docs.sentry.io/product/crons/) allows you to monitor the uptime and performance of any scheduled,
recurring job in your application.

To instrument your cron triggers, use the `Sentry.withMonitor` API in your
[`Scheduled` handler](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/).

```js
export default {
async scheduled(event, env, ctx) {
ctx.waitUntil(
Sentry.withMonitor('your-cron-name', () => {
return doSomeTaskOnASchedule();
}),
);
},
};
```

You can also use supply a monitor config to upsert cron monitors with additional metadata:

```js
const monitorConfig = {
schedule: {
type: 'crontab',
value: '* * * * *',
},
checkinMargin: 2, // In minutes. Optional.
maxRuntime: 10, // In minutes. Optional.
timezone: 'America/Los_Angeles', // Optional.
};

export default {
async scheduled(event, env, ctx) {
Sentry.withMonitor('your-cron-name', () => doSomeTaskOnASchedule(), monitorConfig);
},
};
```
- [Report a bug](https://github.com/getsentry/sentry-javascript/issues/new/choose)
- [Contributing](https://github.com/getsentry/sentry-javascript/blob/develop/CONTRIBUTING.md)
Loading