feat(nuxt): Add Cloudflare Nitro plugin

packages/core/src/utils/meta.ts

@@ -1,3 +1,4 @@
+import type { SerializedTraceData } from '../types-hoist/tracing';
 import { getTraceData } from './traceData';
 
 /**
@@ -21,8 +22,8 @@ import { getTraceData } from './traceData';
  * ```
  *
  */
-export function getTraceMetaTags(): string {
-  return Object.entries(getTraceData())
+export function getTraceMetaTags(traceData?: SerializedTraceData): string {
+  return Object.entries(traceData || getTraceData())
     .map(([key, value]) => `<meta name="${key}" content="${value}"/>`)
     .join('\n');
 }

packages/core/test/lib/utils/meta.test.ts

@@ -29,4 +29,20 @@ describe('getTraceMetaTags', () => {
 
     expect(getTraceMetaTags()).toBe('');
   });
+
+  it('uses provided traceData instead of calling getTraceData()', () => {
+    const getTraceDataSpy = vi.spyOn(TraceDataModule, 'getTraceData');
+
+    const customTraceData = {
+      'sentry-trace': 'ab12345678901234567890123456789012-1234567890abcdef-1',
+      baggage:
+        'sentry-environment=test,sentry-public_key=public12345,sentry-trace_id=ab12345678901234567890123456789012,sentry-sample_rate=0.5',
+    };
+
+    expect(getTraceMetaTags(customTraceData))
+      .toBe(`<meta name="sentry-trace" content="ab12345678901234567890123456789012-1234567890abcdef-1"/>
+<meta name="baggage" content="sentry-environment=test,sentry-public_key=public12345,sentry-trace_id=ab12345678901234567890123456789012,sentry-sample_rate=0.5"/>`);
+
+    expect(getTraceDataSpy).not.toHaveBeenCalled();
+  });
 });

packages/nuxt/package.json

@@ -33,6 +33,10 @@
       "types": "./build/module/types.d.ts",
       "import": "./build/module/module.mjs",
       "require": "./build/module/module.cjs"
+    },
+    "./module/plugins": {
+      "types": "./build/module/runtime/plugins/index.d.ts",
+      "import": "./build/module/runtime/plugins/index.js"
     }
   },
   "publishConfig": {
@@ -45,6 +49,7 @@
     "@nuxt/kit": "^3.13.2",
     "@sentry/browser": "9.33.0",
     "@sentry/core": "9.33.0",
+    "@sentry/cloudflare": "9.33.0",
     "@sentry/node": "9.33.0",
     "@sentry/rollup-plugin": "^3.5.0",
     "@sentry/vite-plugin": "^3.5.0",

packages/nuxt/src/runtime/hooks/captureErrorHook.ts

@@ -0,0 +1,47 @@
+import { captureException, getClient, getCurrentScope } from '@sentry/core';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { H3Error } from 'h3';
+import type { CapturedErrorContext } from 'nitropack';
+import { extractErrorContext, flushIfServerless } from '../utils';
+
+/**
+ *  Hook that can be added in a Nitro plugin. It captures an error and sends it to Sentry.
+ */
+export async function sentryCaptureErrorHook(error: Error, errorContext: CapturedErrorContext): Promise<void> {
+  const sentryClient = getClient();
+  const sentryClientOptions = sentryClient?.getOptions();
+
+  if (
+    sentryClientOptions &&
+    'enableNitroErrorHandler' in sentryClientOptions &&
+    sentryClientOptions.enableNitroErrorHandler === false
+  ) {
+    return;
+  }
+
+  // Do not handle 404 and 422
+  if (error instanceof H3Error) {
+    // Do not report if status code is 3xx or 4xx
+    if (error.statusCode >= 300 && error.statusCode < 500) {
+      return;
+    }
+  }
+
+  const { method, path } = {
+    method: errorContext.event?._method ? errorContext.event._method : '',
+    path: errorContext.event?._path ? errorContext.event._path : null,
+  };
+
+  if (path) {
+    getCurrentScope().setTransactionName(`${method} ${path}`);
+  }
+
+  const structuredContext = extractErrorContext(errorContext);
+
+  captureException(error, {
+    captureContext: { contexts: { nuxt: structuredContext } },
+    mechanism: { handled: false },
+  });
+
+  await flushIfServerless();
+}

packages/nuxt/src/runtime/plugins/index.ts

@@ -0,0 +1,2 @@
+// fixme: Can this be exported like this?
+export { sentryCloudflareNitroPlugin } from './sentry-cloudflare.server';

packages/nuxt/src/runtime/plugins/sentry-cloudflare.server.ts

@@ -0,0 +1,155 @@
+import type { ExecutionContext, IncomingRequestCfProperties } from '@cloudflare/workers-types';
+import type { CloudflareOptions } from '@sentry/cloudflare';
+import { setAsyncLocalStorageAsyncContextStrategy, wrapRequestHandler } from '@sentry/cloudflare';
+import { getDefaultIsolationScope, getIsolationScope, getTraceData, logger } from '@sentry/core';
+import type { H3Event } from 'h3';
+import type { NitroApp, NitroAppPlugin } from 'nitropack';
+import type { NuxtRenderHTMLContext } from 'nuxt/app';
+import { sentryCaptureErrorHook } from '../hooks/captureErrorHook';
+import { addSentryTracingMetaTags } from '../utils';
+
+interface CfEventType {
+  protocol: string;
+  host: string;
+  method: string;
+  headers: Record<string, string>;
+  context: {
+    cf: {
+      httpProtocol?: string;
+      country?: string;
+      // ...other CF properties
+    };
+    cloudflare: {
+      context: ExecutionContext;
+      request?: Record<string, unknown>;
+      env?: Record<string, unknown>;
+    };
+  };
+}
+
+function isEventType(event: unknown): event is CfEventType {
+  if (event === null || typeof event !== 'object') return false;
+
+  return (
+    // basic properties
+    'protocol' in event &&
+    'host' in event &&
+    typeof event.protocol === 'string' &&
+    typeof event.host === 'string' &&
+    // context property
+    'context' in event &&
+    typeof event.context === 'object' &&
+    event.context !== null &&
+    // context.cf properties
+    'cf' in event.context &&
+    typeof event.context.cf === 'object' &&
+    event.context.cf !== null &&
+    // context.cloudflare properties
+    'cloudflare' in event.context &&
+    typeof event.context.cloudflare === 'object' &&
+    event.context.cloudflare !== null &&
+    'context' in event.context.cloudflare
+  );
+}
+
+/**
+ * Sentry Cloudflare Nitro plugin for when using the "cloudflare-pages" preset in Nuxt.
+ * This plugin automatically sets up Sentry error monitoring and performance tracking for Cloudflare Pages projects.
+ *
+ * Instead of adding a `sentry.server.config.ts` file, export this plugin in the `server/plugins` directory
+ * with the necessary Sentry options to enable Sentry for your Cloudflare Pages project.
+ *
+ *
+ * @example Basic usage
+ * ```ts
+ * // nitro/plugins/sentry.ts
+ * import { defineNitroPlugin } from '#imports'
+ * import { sentryCloudflareNitroPlugin } from '@sentry/nuxt/module/plugins'
+ *
+ * export default defineNitroPlugin(sentryCloudflareNitroPlugin({
+ *   dsn: 'https://[email protected]/0',
+ *   tracesSampleRate: 1.0,
+ * }));
+ * ```
+ *
+ * @example Dynamic configuration with nitroApp
+ * ```ts
+ * // nitro/plugins/sentry.ts
+ * import { defineNitroPlugin } from '#imports'
+ * import { sentryCloudflareNitroPlugin } from '@sentry/nuxt/module/plugins'
+ *
+ * export default defineNitroPlugin(sentryCloudflareNitroPlugin(nitroApp => ({
+ *   dsn: 'https://[email protected]/0',
+ *   debug: nitroApp.h3App.options.debug
+ * })));
+ * ```
+ */
+export const sentryCloudflareNitroPlugin =
+  (optionsOrFn: CloudflareOptions | ((nitroApp: NitroApp) => CloudflareOptions)): NitroAppPlugin =>
+  (nitroApp: NitroApp): void => {
+    const traceDataMap = new WeakMap<object, ReturnType<typeof getTraceData>>();
+
+    nitroApp.localFetch = new Proxy(nitroApp.localFetch, {
+      async apply(handlerTarget, handlerThisArg, handlerArgs: [string, unknown]) {
+        setAsyncLocalStorageAsyncContextStrategy();
+
+        const cloudflareOptions = typeof optionsOrFn === 'function' ? optionsOrFn(nitroApp) : optionsOrFn;
+        const pathname = handlerArgs[0];
+        const event = handlerArgs[1];
+
+        if (!isEventType(event)) {
+          logger.log("Nitro Cloudflare plugin did not detect a Cloudflare event type. Won't patch Cloudflare handler.");
+          return handlerTarget.apply(handlerThisArg, handlerArgs);
+        } else {
+          // Usually, the protocol already includes ":"
+          const url = `${event.protocol}${event.protocol.endsWith(':') ? '' : ':'}//${event.host}${pathname}`;
+          const request = new Request(url, {
+            method: event.method,
+            headers: event.headers,
+            cf: event.context.cf,
+          }) as Request<unknown, IncomingRequestCfProperties<unknown>>;
+
+          const requestHandlerOptions = {
+            options: cloudflareOptions,
+            request,
+            context: event.context.cloudflare.context,
+          };
+
+          return wrapRequestHandler(requestHandlerOptions, () => {
+            const isolationScope = getIsolationScope();
+            const newIsolationScope =
+              isolationScope === getDefaultIsolationScope() ? isolationScope.clone() : isolationScope;
+
+            const traceData = getTraceData();
+            if (traceData && Object.keys(traceData).length > 0) {
+              // Storing trace data in the WeakMap using event.context.cf as key for later use in HTML meta-tags
+              traceDataMap.set(event.context.cf, traceData);
+              logger.log('Stored trace data for later use in HTML meta-tags: ', traceData);
+            }
+
+            logger.log(
+              `Patched Cloudflare handler (\`nitroApp.localFetch\`). ${
+                isolationScope === newIsolationScope ? 'Using existing' : 'Created new'
+              } isolation scope.`,
+            );
+
+            return handlerTarget.apply(handlerThisArg, handlerArgs);
+          });
+        }
+      },
+    });
+
+    // @ts-expect-error - 'render:html' is a valid hook name in the Nuxt context
+    nitroApp.hooks.hook('render:html', (html: NuxtRenderHTMLContext, { event }: { event: H3Event }) => {
+      const storedTraceData = event?.context?.cf ? traceDataMap.get(event.context.cf) : undefined;
+
+      if (storedTraceData && Object.keys(storedTraceData).length > 0) {
+        logger.log('Using stored trace data for HTML meta-tags: ', storedTraceData);
+        addSentryTracingMetaTags(html.head, storedTraceData);
+      } else {
+        addSentryTracingMetaTags(html.head);
+      }
+    });
+
+    nitroApp.hooks.hook('error', sentryCaptureErrorHook);
+  };

packages/nuxt/src/runtime/plugins/sentry.server.ts

@@ -1,96 +1,23 @@
-import {
-  flush,
-  getDefaultIsolationScope,
-  getIsolationScope,
-  GLOBAL_OBJ,
-  logger,
-  vercelWaitUntil,
-  withIsolationScope,
-} from '@sentry/core';
-import * as SentryNode from '@sentry/node';
+import { getDefaultIsolationScope, getIsolationScope, logger, withIsolationScope } from '@sentry/core';
 // eslint-disable-next-line import/no-extraneous-dependencies
-import { type EventHandler, H3Error } from 'h3';
+import { type EventHandler } from 'h3';
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { defineNitroPlugin } from 'nitropack/runtime';
 import type { NuxtRenderHTMLContext } from 'nuxt/app';
-import { addSentryTracingMetaTags, extractErrorContext } from '../utils';
+import { sentryCaptureErrorHook } from '../hooks/captureErrorHook';
+import { addSentryTracingMetaTags, flushIfServerless } from '../utils';
 
 export default defineNitroPlugin(nitroApp => {
   nitroApp.h3App.handler = patchEventHandler(nitroApp.h3App.handler);
 
-  nitroApp.hooks.hook('error', async (error, errorContext) => {
-    const sentryClient = SentryNode.getClient();
-    const sentryClientOptions = sentryClient?.getOptions();
-
-    if (
-      sentryClientOptions &&
-      'enableNitroErrorHandler' in sentryClientOptions &&
-      sentryClientOptions.enableNitroErrorHandler === false
-    ) {
-      return;
-    }
-
-    // Do not handle 404 and 422
-    if (error instanceof H3Error) {
-      // Do not report if status code is 3xx or 4xx
-      if (error.statusCode >= 300 && error.statusCode < 500) {
-        return;
-      }
-    }
-
-    const { method, path } = {
-      method: errorContext.event?._method ? errorContext.event._method : '',
-      path: errorContext.event?._path ? errorContext.event._path : null,
-    };
-
-    if (path) {
-      SentryNode.getCurrentScope().setTransactionName(`${method} ${path}`);
-    }
-
-    const structuredContext = extractErrorContext(errorContext);
-
-    SentryNode.captureException(error, {
-      captureContext: { contexts: { nuxt: structuredContext } },
-      mechanism: { handled: false },
-    });
-
-    await flushIfServerless();
-  });
+  nitroApp.hooks.hook('error', sentryCaptureErrorHook);
 
   // @ts-expect-error - 'render:html' is a valid hook name in the Nuxt context
   nitroApp.hooks.hook('render:html', (html: NuxtRenderHTMLContext) => {
     addSentryTracingMetaTags(html.head);
   });
 });
 
-async function flushIfServerless(): Promise<void> {
-  const isServerless =
-    !!process.env.FUNCTIONS_WORKER_RUNTIME || // Azure Functions
-    !!process.env.LAMBDA_TASK_ROOT || // AWS Lambda
-    !!process.env.VERCEL ||
-    !!process.env.NETLIFY;
-
-  // @ts-expect-error This is not typed
-  if (GLOBAL_OBJ[Symbol.for('@vercel/request-context')]) {
-    vercelWaitUntil(flushWithTimeout());
-  } else if (isServerless) {
-    await flushWithTimeout();
-  }
-}
-
-async function flushWithTimeout(): Promise<void> {
-  const sentryClient = SentryNode.getClient();
-  const isDebug = sentryClient ? sentryClient.getOptions().debug : false;
-
-  try {
-    isDebug && logger.log('Flushing events...');
-    await flush(2000);
-    isDebug && logger.log('Done flushing events');
-  } catch (e) {
-    isDebug && logger.log('Error while flushing events:\n', e);
-  }
-}
-
 function patchEventHandler(handler: EventHandler): EventHandler {
   return new Proxy(handler, {
     async apply(handlerTarget, handlerThisArg, handlerArgs: Parameters<EventHandler>) {