# Cloudflare | Sentry for Cloudflare

Use this guide for general instructions on using the Sentry SDK with Cloudflare. If you're using any of the listed frameworks, follow their specific setup instructions:

* **[Astro](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/astro.md)**
* **[Hono](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/hono.md)**
* **[Hydrogen](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/hydrogen-react-router.md)**
* **[Nuxt](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt.md)**
* **[Remix](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/remix.md)**
* **[SvelteKit](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/sveltekit.md)**

## [Prerequisites](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#prerequisites)

You need:

* A Sentry [account](https://sentry.io/signup/) and [project](https://docs.sentry.io/product/projects.md)
* Your application up and running

## [Step 1: Install](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#step-1-install)

Choose the features you want to configure, and this guide will show you how:

Error Monitoring\[ ]Logs\[ ]Tracing

Want to learn more about these features?

* [**Issues**](https://docs.sentry.io/product/issues.md) (always enabled): Sentry's core error monitoring product that automatically reports errors, uncaught exceptions, and unhandled rejections. If you have something that looks like an exception, Sentry can capture it.
* [**Tracing**](https://docs.sentry.io/product/tracing.md): Track software performance while seeing the impact of errors across multiple systems. For example, distributed tracing allows you to follow a request from the frontend to the backend and back.
* [**Logs**](https://docs.sentry.io/product/explore/logs.md): Centralize and analyze your application logs to correlate them with errors and performance issues. Search, filter, and visualize log data to understand what's happening in your applications.

### [Install the Sentry SDK](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#install-the-sentry-sdk)

Run the command for your preferred package manager to add the Sentry SDK to your application:

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

## [Step 2: Configure](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#step-2-configure)

The main Sentry configuration should happen as early as possible in your app's lifecycle.

### [Wrangler Configuration](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#wrangler-configuration)

Since the SDK needs access to the `AsyncLocalStorage` API, you need to set either the `nodejs_compat` or `nodejs_als` compatibility flags in your `wrangler.(jsonc|toml)` configuration file:

`wrangler.jsonc`

```jsonc
{
  "compatibility_flags": [
    "nodejs_als",
    // "nodejs_compat"
  ],
}
```

Additionally, add the `CF_VERSION_METADATA` binding in the same file:

`wrangler.jsonc`

```jsonc
{
  // ...
  "version_metadata": {
    "binding": "CF_VERSION_METADATA",
  },
}
```

### [Setup for Cloudflare Workers](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#setup-for-cloudflare-workers)

Wrap your worker handler with the `withSentry` function, for example, in your `index.ts` file, to initialize the Sentry SDK and hook into the environment:

`index.ts`

```typescript
import * as Sentry from "@sentry/cloudflare";

export default Sentry.withSentry(
  (env: Env) => {
    const { id: versionId } = env.CF_VERSION_METADATA;

    return {
      dsn: "___PUBLIC_DSN___",

      release: versionId,

      // Adds request headers and IP for users, for more info visit:
      // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#sendDefaultPii
      sendDefaultPii: true,
      // ___PRODUCT_OPTION_START___ logs

      // Enable logs to be sent to Sentry
      enableLogs: true,
      // ___PRODUCT_OPTION_END___ logs
      // ___PRODUCT_OPTION_START___ performance

      // 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,
      // ___PRODUCT_OPTION_END___ performance
    };
  },
  {
    async fetch(request, env, ctx) {
      // Your worker logic here
      return new Response("Hello World!");
    },
  },
);
```

### [Setup for Cloudflare Pages](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#setup-for-cloudflare-pages)

To use the Sentry SDK, add the `sentryPagesPlugin` as [middleware to your Cloudflare Pages application](https://developers.cloudflare.com/pages/functions/middleware/). For this, we recommend you create a `functions/_middleware.js` file to set up the middleware for your entire app:

`functions/_middleware.js`

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

export const onRequest = [
  // Make sure Sentry is the first middleware
  Sentry.sentryPagesPlugin((context) => {
    const { id: versionId } = env.CF_VERSION_METADATA;

    return {
      dsn: "___PUBLIC_DSN___",

      release: versionId,

      // Adds request headers and IP for users, for more info visit:
      // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#sendDefaultPii
      sendDefaultPii: true,
      // ___PRODUCT_OPTION_START___ logs

      // Enable logs to be sent to Sentry
      enableLogs: true,
      // ___PRODUCT_OPTION_END___ logs
      // ___PRODUCT_OPTION_START___ performance

      // 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,
      // ___PRODUCT_OPTION_END___ performance
    };
  }),
  // Add more middlewares here
];
```

Don't have access to onRequest?

If you don't have access to the `onRequest` middleware API, you can use the `wrapRequestHandler` API instead. For example:

```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),
  );
};
```

## [Step 3: Add Readable Stack Traces With Source Maps (Optional)](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#step-3-add-readable-stack-traces-with-source-maps-optional)

The stack traces in your Sentry errors probably won't look like your actual code without unminifying them. To fix this, upload your [source maps](https://docs.sentry.io/platforms/javascript/guides/cloudflare/sourcemaps.md) to Sentry.

First, set the `upload_source_maps` option to `true` in your `wrangler.(jsonc|toml)` config file to enable source map uploading:

`wrangler.jsonc`

```jsonc
{
  "upload_source_maps": true,
}
```

Next, run the Sentry Wizard to finish your setup:

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

## [Step 4: Verify Your Setup](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#step-4-verify-your-setup)

Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.

### [Issues](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#issues)

First, let's make sure Sentry is correctly capturing errors and creating issues in your project.

#### [Cloudflare Workers](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#cloudflare-workers)

Add the following code snippet to your main worker file to create a `/debug-sentry` route that triggers an error when called:

`index.js`

```javascript
export default {
  async fetch(request) {
    const url = new URL(request.url);

    if (url.pathname === "/debug-sentry") {
      throw new Error("My first Sentry error!");
    }

    // Your existing routes and logic here...
    return new Response("...");
  },
};
```

#### [Cloudflare Pages](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#cloudflare-pages)

Create a new route that throws an error when called by adding the following code snippet to a file in your `functions` directory, such as `functions/debug-sentry.js`:

`debug-sentry.js`

```javascript
export async function onRequest(context) {
  throw new Error("My first Sentry error!");
}
```

### [Tracing](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#tracing)

To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes to run your code.

#### [Cloudflare Workers](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#cloudflare-workers-1)

`index.js`

```javascript
export default {
  async fetch(request) {
    const url = new URL(request.url);

    if (url.pathname === "/debug-sentry") {
      await Sentry.startSpan(
        {
          op: "test",
          name: "My First Test Transaction",
        },
        async () => {
          await new Promise((resolve) => setTimeout(resolve, 100)); // Wait for 100ms
          throw new Error("My first Sentry error!");
        },
      );
    }

    // Your existing routes and logic here...
    return new Response("...");
  },
};
```

#### [Cloudflare Pages](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#cloudflare-pages-1)

`debug-sentry.js`

```javascript
export async function onRequest(context) {
  await Sentry.startSpan(
    {
      op: "test",
      name: "My First Test Transaction",
    },
    async () => {
      await new Promise((resolve) => setTimeout(resolve, 100)); // Wait for 100ms
      throw new Error("My first Sentry error!");
    },
  );
}
```

### [View Captured Data in Sentry](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#view-captured-data-in-sentry)

Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear).

Need help locating the captured errors in your Sentry project?

1. Open the [**Issues**](https://sentry.io/issues) page and select an error from the issues list to view the full details and context of this error. For more details, see this [interactive walkthrough](https://docs.sentry.io/product/sentry-basics/integrate-frontend/generate-first-error.md#ui-walkthrough).
2. Open the [**Traces**](https://sentry.io/explore/traces) page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click [here](https://docs.sentry.io/product/sentry-basics/distributed-tracing/generate-first-error.md#ui-walkthrough).
3. Open the [**Logs**](https://sentry.io/explore/logs) page and filter by service, environment, or search keywords to view log entries from your application. For an interactive UI walkthrough, click [here](https://docs.sentry.io/product/explore/logs.md#overview).

## [Next Steps](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md#next-steps)

At this point, you should have integrated Sentry and should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:

* Learn how to [manually capture errors](https://docs.sentry.io/platforms/javascript/guides/cloudflare/usage.md)
* Continue to [customize your configuration](https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration.md)
* Make use of [Cloudflare-specific features](https://docs.sentry.io/platforms/javascript/guides/cloudflare/features.md)
* Get familiar with [Sentry's product features](https://docs.sentry.io/product.md) like tracing, insights, and alerts

Are you having problems setting up the SDK?

* Check out setup instructions for popular [frameworks on Cloudflare](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks.md)
* Find various support topics in [troubleshooting](https://docs.sentry.io/platforms/javascript/guides/cloudflare/troubleshooting.md)
* [Get support](https://sentry.zendesk.com/hc/en-us/)