---
title: "Nuxt on Cloudflare"
description: "Learn how to instrument your Nuxt app on Cloudflare Workers and Pages and capture your first errors with Sentry."
url: https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt/
---

# Nuxt on Cloudflare | Sentry for Cloudflare

This guide will show you how to set up the SDK with Nitro's `cloudflare_module` (or their deprecated `cloudflare-pages`) deployment preset.

## [Prerequisites](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt.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
* Nuxt version `3.7.0` or above (`3.14.0`+ recommended)

Are you using Nuxt version < 3.14.0?

Add the following overrides:

`package.json`

```json
"overrides": {
  "ofetch": "^1.4.0",
  "@vercel/nft": "^0.27.4"
}
```

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

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

Error Monitoring\[ ]Tracing\[ ]Session Replay\[ ]Logs\[ ]User Feedback

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.
* [**Session Replay**](https://docs.sentry.io/product/explore/session-replay/web.md):
  <!-- -->
  Get to the root cause of an issue faster by viewing a video-like reproduction of what was happening in the user's browser before, during, and after the problem.
* [**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.
* [**User Feedback**](https://docs.sentry.io/product/user-feedback.md):
  <!-- -->
  Collect feedback directly from users when they encounter errors, allowing them to describe what happened and provide context that helps you understand and resolve issues faster.

### [Install the Sentry SDK](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt.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/nuxt --save
```

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

### [Apply Instrumentation to Your App](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt.md#apply-instrumentation-to-your-app)

Add the Sentry Nuxt module to your `nuxt.config.ts` file:

`nuxt.config.ts`

```javascript
export default defineNuxtConfig({
  modules: ["@sentry/nuxt/module"],
});
```

### [Configure Client-side Sentry](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt.md#configure-client-side-sentry)

Add a `sentry.client.config.ts` file to the root of your project (this is probably the same level as the `package.json`). In this file, import and initialize Sentry, specifying any SDK options for the client:

`sentry.client.config.ts`

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

Sentry.init({
  // If set up, you can use the Nuxt runtime config here
  // dsn: useRuntimeConfig().public.sentry.dsn
  // modify depending on your custom runtime config
  dsn: "___PUBLIC_DSN___",

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

  // Replay may only be enabled for the client-side
  integrations: [
    Sentry.replayIntegration(),
    // ___PRODUCT_OPTION_START___ user-feedback
    Sentry.feedbackIntegration({
      // Additional SDK configuration goes in here, for example:
      colorScheme: "system",
    }),
    // ___PRODUCT_OPTION_END___ user-feedback
  ],
  // ___PRODUCT_OPTION_END___ session-replay
  // ___PRODUCT_OPTION_START___ performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ session-replay

  // Capture Replay for 10% of all sessions,
  // plus for 100% of sessions with an error
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ session-replay
  // ___PRODUCT_OPTION_START___ logs

  // Enable logs to be sent to Sentry
  enableLogs: true,
  // ___PRODUCT_OPTION_END___ logs
});
```

We recommend you store your Sentry [Data Source Name](https://docs.sentry.io/concepts/key-terms/dsn-explainer.md) (DSN) in an environment variable and configure it via the Nuxt runtime config like so:

`nuxt.config.ts`

```javascript
export default defineNuxtConfig({
  modules: ["@sentry/nuxt/module"],
  runtimeConfig: {
    public: {
      sentry: {
        dsn: process.env.NUXT_PUBLIC_SENTRY_DSN, // Use a public environment variable for the DSN
      },
    },
  },
});
```

This allows you to access the DSN using `useRuntimeConfig().public.sentry.dsn`.

### [Configure Cloudflare for Sentry](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt.md#configure-cloudflare-for-sentry)

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

`wrangler.jsonc`

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

### [Release Configuration (Optional)](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt.md#release-configuration-optional)

If you don't set the `release` option manually, the SDK automatically detects it from these sources (in order of priority):

1. The `SENTRY_RELEASE` environment variable
2. The `CF_VERSION_METADATA.id` binding (if configured)

To enable automatic release detection via Cloudflare's version metadata, add the `CF_VERSION_METADATA` binding in your wrangler configuration. This provides access to the [Cloudflare version metadata](https://developers.cloudflare.com/workers/runtime-apis/bindings/version-metadata/):

Using an SDK version before 10.35.0?

In earlier versions, you need to manually extract `CF_VERSION_METADATA.id` and pass it as the `release` option:

```javascript
Sentry.withSentry(
  (env) => ({
    dsn: "___PUBLIC_DSN___",
    release: env.CF_VERSION_METADATA?.id,
  }),
  // ...
);
```

`wrangler.jsonc`

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

#### [Add the Nitro Plugin](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt.md#add-the-nitro-plugin)

##### Important

If you have an existing `sentry.server.config.ts` file, delete it, as it will conflict with the Cloudflare setup.

To enable Sentry for your Nuxt app on Cloudflare, create a new file in `server/plugins` and add the following code to it:

`server/plugins/sentry-cloudflare-plugin.ts`

```TypeScript
import { sentryCloudflareNitroPlugin } from '@sentry/nuxt/module/plugins'

export default defineNitroPlugin(sentryCloudflareNitroPlugin({
  dsn: '___PUBLIC_DSN___',
  tracesSampleRate: 1.0,
}))
```

Or, if you need access to `nitroApp`:

`server/plugins/sentry-cloudflare-plugin.ts`

```TypeScript
import { sentryCloudflareNitroPlugin } from '@sentry/nuxt/module/plugins'

export default defineNitroPlugin(sentryCloudflareNitroPlugin((nitroApp: NitroApp) => {
  // You can access `nitroApp` here if needed
  return {
    dsn: '___PUBLIC_DSN___',
    tracesSampleRate: 1.0,
  }
}))
```

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

To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slugs in the `sentry` options inside your configuration file:

These `sentry` options only affect the **build time** of the SDK.

`nuxt.config.ts`

```javascript
export default defineNuxtConfig({
  modules: ["@sentry/nuxt/module"],

  sentry: {
    org: "___ORG_SLUG___",
    project: "___PROJECT_SLUG___",
    // store your auth token in an environment variable
    authToken: process.env.SENTRY_AUTH_TOKEN,
  },
});
```

To keep your auth token secure, always store it in an environment variable instead of directly in your files:

`.env`

```bash
SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
```

Using environment variables in Vite configs

Vite doesn't automatically load `.env` files into `process.env` when evaluating the config file. If you store your auth token in a `.env` file and want to access it via `process.env.SENTRY_AUTH_TOKEN`, use Vite's [`loadEnv`](https://vite.dev/guide/api-javascript#loadenv) helper:

`vite.config.js`

```javascript
import { defineConfig, loadEnv } from "vite";

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), "");

  return {
    plugins: [
      sentryVitePlugin({
        authToken: env.SENTRY_AUTH_TOKEN,
        // ...
      }),
    ],
  };
});
```

Alternatively, use a `.env.sentry-build-plugin` file, which the Sentry plugin reads automatically.

While Nuxt generates source maps on the server side by default, you need to explicitly enable client-side source maps in your Nuxt configuration:

`nuxt.config.ts`

```javascript
export default defineNuxtConfig({

  sourcemap: { client: "hidden" },

});
```

The `hidden` option enables source map generation while preventing source map reference comments that would normally appear at the end of each generated file in the build output.

## [Step 4: Verify Your Setup](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt.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/frameworks/nuxt.md#issues)

To verify that Sentry captures errors and creates issues in your Sentry project, create a test page with a button:

`pages/example-error.vue`

```html
<script setup>
  import * as Sentry from "@sentry/nuxt";

  function triggerClientError() {
    throw new Error("Nuxt Button Error");
  }
</script>

<template>
  <button id="errorBtn" @click="triggerClientError">
    Throw Client Error
  </button>
</template>
```

Open the page in a browser (for most Nuxt applications, this will be at localhost:3000) and click the button to trigger a frontend error.

##### Important

Errors triggered from within your browser's developer tools (like the browser console) are sandboxed, so they will not trigger Sentry's error monitoring.

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

To test tracing, create a test API route `server/api/sentry-example.get.ts`:

`server/api/sentry-example.get.ts`

```js
export default defineEventHandler((event) => {
  throw new Error("Sentry Example API Route Error");
});
```

Then update the test page by including a new button that executes a function to fetch your API route:

`pages/example-error.vue`

```html
<script setup>
  import * as Sentry from "@sentry/nuxt";

  function triggerClientError() {
    throw new Error("Nuxt Button Error");
  }

  function getSentryData() {
    Sentry.startSpan(
      {
        name: "Example Frontend Span",
        op: "test",
      },
      async () => {
        await $fetch("/api/sentry-example");
      },
    );
  }
</script>

<template>
  <button id="errorBtn" @click="triggerClientError">
    Throw Client Error
  </button>
  <button type="button" @click="getSentryData">Throw Server Error</button>
</template>
```

Once you have your test code in place, you need to build your project since Sentry's **server-side monitoring doesn't work in development** mode.

After running your project:

1. Open your test page in a browser (for most Nuxt applications, this will be at localhost:3000)
2. Click the "Throw Client Error" button to trigger an error in the frontend
3. Click the "Throw Server Error" button to trigger an error within the API route and start a performance trace to measure the time it takes for the API request to complete.

### [Logs NEW](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt.md#logs-)

To verify that Sentry catches your logs, add some log statements to your application:

```javascript
Sentry.logger.info("User example action completed");

Sentry.logger.warn("Slow operation detected", {
  operation: "data_fetch",
  duration: 3500,
});

Sentry.logger.error("Validation failed", {
  field: "email",
  reason: "Invalid email",
});
```

### [View Captured Data in Sentry](https://docs.sentry.io/platforms/javascript/guides/cloudflare/frameworks/nuxt.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?

* Open the
  <!-- -->
  [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/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).
* Open the
  <!-- -->
  [**Traces**](https://sentry.io/orgredirect/organizations/:orgslug/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).
* Open the
  <!-- -->
  [**Replays**](https://sentry.io/orgredirect/organizations/:orgslug/replays/)
  <!-- -->
  page and select an entry from the list to get a detailed view where you can replay the interaction and get more information to help you troubleshoot.
* Open the
  <!-- -->
  [**Logs**](https://sentry.io/orgredirect/organizations/:orgslug/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).
* Open the
  <!-- -->
  [**User Feedback**](https://sentry.io/orgredirect/organizations/:orgslug/feedback/)
  <!-- -->
  page and click on individual feedback to see more details all in one view. For more information, click [here](https://docs.sentry.io/product/user-feedback.md).

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

At this point, you should have integrated Sentry into your Nuxt application 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:

* Explore [practical guides](https://docs.sentry.io/guides.md) on what to monitor, log, track, and investigate after setup
* Learn how to [manually capture errors](https://docs.sentry.io/platforms/javascript/guides/nuxt/usage.md)
* Continue to [customize your configuration](https://docs.sentry.io/platforms/javascript/guides/nuxt/configuration.md)
* Get familiar with [Sentry's product features](https://docs.sentry.io/product.md) like tracing, insights, and alerts
* Learn how to [track your Vue components or your Pinia store](https://docs.sentry.io/platforms/javascript/guides/nuxt/features.md)

Are you having problems setting up the SDK?

* Find various support topics in [Cloudflare troubleshooting](https://docs.sentry.io/platforms/javascript/guides/cloudflare/troubleshooting.md) and [Nuxt troubleshooting](https://docs.sentry.io/platforms/javascript/guides/nuxt/troubleshooting.md)
* [Get support](https://sentry.zendesk.com/hc/en-us/)