How to add Sentry monitoring to a Webflow Cloud app

How to set up Sentry error tracking on a Webflow Cloud Next.js app

Webflow Cloud runs on Cloudflare Workers, which is a managed environment. You don't control the runtime directly, and its built-in observability includes request-level metrics: request count, CPU time, and memory usage. Useful for capacity planning.

If you want to add debugging, Sentry provides monitoring layers such as error grouping, stack traces, performance traces, and session replay. When a Route Handler throws, you see exactly where. When a client component crashes, you see exactly why.

In this article, we walk through the full manual setup, including Cloudflare-specific tunnel configurations, plus the five silent failure modes and their fixes.

What do you need to add Sentry to a Webflow Cloud App?

You need a Sentry account (the free tier works) and a Webflow Cloud App running Next.js. You'll create five files, modify one, and add four environment variables. The Sentry wizard can generate most of this automatically, but I walk through the manual setup here so each piece is understandable, not just present.

If you're starting from scratch on the Cloud App side, this Webflow Cloud guide covers the initial scaffold. The manual setup below works for both projects scaffolded through the Webflow CLI and existing apps brought to Webflow Cloud.

Each step includes the reasoning behind the configuration, so you understand what to do when something doesn't work, rather than just having configuration files without context.

4 steps to add Sentry monitoring to a Webflow Cloud App

The setup touches five files and one config file. Steps 1 and 2 install the SDK and create the Sentry initialization files. Step 3 handles environment variables and the Cloudflare-specific tunnel fix that most Sentry guides miss. Step 4 verifies the full pipeline and sets up alerts.

Here is how each step fits together.

1. Install the Sentry SDK and wrap your Next.js config

Two things happen here: the package install brings in the SDK, and wrapping next.config.ts with withSentryConfig activates source map uploads and automatic instrumentation across all Route Handlers and Server Components.

The <a href="https://docs.sentry.io/platforms/javascript/guides/nextjs/" target="_blank" rel="noopener noreferrer">@sentry/nextjs</a> package handles both client and server instrumentation with a single install:

npm install @sentry/nextjs --save

Then open next.config.ts (or next.config.js if that's what the scaffold generated) and wrap your existing config with withSentryConfig:

// next.config.ts
import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs";

const nextConfig: NextConfig = {
  basePath: "/app",       // your Webflow Cloud mount path
  assetPrefix: "/app",
};

export default withSentryConfig(nextConfig, {
  org: "your-org-slug",
  project: "your-project-slug",

  // Upload source maps — requires SENTRY_AUTH_TOKEN in CI
  authToken: process.env.SENTRY_AUTH_TOKEN,
  widenClientFileUpload: true,

  // Suppress upload logs outside of CI
  silent: !process.env.CI,

  // Route Sentry events through your Next.js server
  // This is required for Webflow Cloud — see Step 3 for why
  tunnelRoute: "/sentry-tunnel",
});

withSentryConfig injects Sentry's webpack plugin into the build. It handles source map uploads during deployment and sets up automatic instrumentation to capture errors from Route Handlers, Server Components, and middleware without any additional wrapping.

The tunnelRoute option matters. I'll explain exactly why in Step 3. For now, keep it exactly as shown.

2. Create the five initialization files

Sentry needs separate init files for the three environments your app runs in: browser, Node.js server (local dev), and Cloudflare Workers edge (production). A fourth file, `instrumentation.ts`, loads the right one at runtime. The fifth, `app/global-error.tsx`, goes in the app directory.

Create the first four in your project root.

Client-side initialization (instrumentation-client.ts)

instrumentation-client.ts runs in the browser. It initializes error capture, session replay, and performance tracing for everything running in the user's browser and exports `onRouterTransitionStart` to instrument client-side route transitions.

Create this file in your project root:

// instrumentation-client.ts
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,

  // Capture 100% of traces in dev, 10% in production
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // Record session replays for 10% of sessions, 100% when an error occurs
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,

  integrations: [Sentry.replayIntegration()],
});

// Instrument client-side route transitions
export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

The tracesSampleRate split (100% in development, 10% in production) prevents trace volume from inflating your Sentry quota on live traffic while keeping full visibility locally.

Edge runtime initialization (sentry.edge.config.ts)

sentry.edge.config.ts runs on Cloudflare Workers (production). Keep this config minimal: the Workers runtime silently drops browser-specific or Node.js-specific integrations, so test anything beyond DSN and sample rate carefully before adding it here.

Create this file in your project root:

// sentry.edge.config.ts
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 0.1,
});

A lower tracesSampleRate in the edge config makes sense: this file is active on every production request, and capturing 100% of traces would quickly consume your Sentry quota at any meaningful traffic volume.

Node.js server initialization (sentry.server.config.ts)

sentry.server.config.ts runs in Node.js (local development). It never deploys to Cloudflare Workers -- `instrumentation.ts` (next) only imports it when `NEXT_RUNTIME` equals "nodejs".

Create this file in your project root:

// sentry.server.config.ts
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 1.0, // 100% in dev
});

Setting tracesSampleRateto1.0 here is intentional. In development, you want full trace coverage to catch issues before they reach production.

Runtime switcher (instrumentation.ts)

instrumentation.ts loads edge or server config based on the active runtime. It reads `NEXT_RUNTIME` at startup and imports the correct Sentry config for the current environment. It also exports `onRequestError`, which captures exceptions from Server Components, Route Handlers, and middleware.

Create this file in your project root:

// instrumentation.ts
import * as Sentry from "@sentry/nextjs";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}

// Captures errors from Server Components, Route Handlers, and middleware
export const onRequestError = Sentry.captureRequestError;

The NEXT_RUNTIME check tells Sentry whether it's running on Cloudflare Workers ("edge") or the local Next.js dev server ("nodejs"). On a deployed Webflow Cloud App, sentry.edge.config.ts is the active config. On your machine running next dev, sentry.server.config.ts runs instead.

Global error boundary (app/global-error.tsx)

Finally, add app/global-error.tsx to catch React render errors that bubble past your error boundaries:

// app/global-error.tsx
"use client";

import * as Sentry from "@sentry/nextjs";
import NextError from "next/error";
import { useEffect } from "react";

export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
  useEffect(() => {
    Sentry.captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <NextError statusCode={0} />
      </body>
    </html>
  );
}

After creating all five files, run the next build locally to confirm the build completes without errors. If Sentry can't find the withSentryConfig configuration, it logs a warning but doesn't fail. Watch for it in the build output.

3. Configure environment variables

This step does two things. First, it adds the four environment variables Sentry needs. Second, it explains why tunnelRoute is required specifically for Webflow Cloud. Skipping this means Sentry captures errors but never delivers them.

Add four variables to .env.local:

NEXT_PUBLIC_SENTRY_DSN=https://your-dsn@o0.ingest.sentry.io/0
SENTRY_AUTH_TOKEN=sntrys_your_auth_token_here
SENTRY_ORG=your-org-slug
SENTRY_PROJECT=your-project-slug

NEXT_PUBLIC_SENTRY_DSN gets the NEXT_PUBLIC_ prefix because the client-side SDK needs it. The DSN is not a secret; it's safe to expose in the browser. SENTRY_AUTH_TOKEN is a secret and must not be committed to version control. Add it to .gitignore alongside .env.local.

Find your DSN in the Sentry dashboard under Project Settings → Client Keys (DSN). Generate an Organization Auth Token at Developer Settings → Auth Tokens. Organization Auth Tokens are automatically scoped for source map uploads and release creation.

Why is tunnelRoute required on Webflow Cloud?

Note: Sentry's docs require compatibility_date: "2025-08-16" or later in wrangler.json for the SDK to send events to Sentry's servers via https.request. Webflow Cloud auto-generates `wrangler.json` with a compatibility date earlier than `2025-08-16`, and you can't edit that file directly. If you set up Sentry without addressing this, errors will be captured in memory but never delivered.

The tunnelRoute: "/sentry-tunnel" you added to next.config.ts in Step 1 solves this. Instead of the Sentry SDK making a direct outbound request from the Worker (which requires the newer compatibility date), it routes events through a Next.js Route Handler using fetch(), which is available on all Cloudflare Workers versions.

The tunnel also stops ad blockers from intercepting Sentry traffic, which I noticed matters more than expected. On one client tool I shipped, roughly 30% of users had some form of content blocking active.

Adding environment variables to Webflow Cloud

Before deploying, add NEXT_PUBLIC_SENTRY_DSN and SENTRY_AUTH_TOKEN to your Webflow Cloud environment. In your Webflow site settings, navigate to Webflow Cloud, open your environment, and add both under Environment Variables:

webflow auth login
webflow cloud deploy

Or push to your connected GitHub branch to trigger an automatic deployment.

4. Verify error capture and set up alerts

After deployment, trigger a test error to confirm the full pipeline works.

Add a button to any page that throws on click:

// Add temporarily to any page to test
<button
  onClick={() => {
    throw new Error("Sentry test — Webflow Cloud");
  }}
>
  Test Sentry
</button>

Click it, then open Issues in your Sentry dashboard. The error should appear within 30 seconds. If it does, client-side error capture is working.

To test server-side capture, throw an intentional error inside a Route Handler and confirm it appears in Sentry. The stack trace should include your source file name and line number, not the compiled output.

That's the SENTRY_AUTH_TOKEN source map upload working. I've shipped Cloud Apps where source maps were missing, and debugging edge errors meant tracing through minified code. The extra setup is worth it for readable traces.

For alerts, go to Alerts → Create Alert in Sentry. The two rules I set for every project are:

• A per-project error-rate alert that fires when new errors spike above a baseline
• An individual issue alert for unhandled exceptions in Route Handlers.

Set the notification channel to email or Slack. Both work without additional configuration.

Expected outcome: Errors from the browser, Server Components, and Cloudflare Workers edge runtime all appear in Sentry with readable stack traces. Session replays record on error. Alerts fire when new issues occur.

What causes Sentry events to disappear silently on Webflow Cloud?

Silent failures are the frustrating part of the Sentry setup. The SDK initializes, no errors appear in the console, but nothing shows up in the dashboard. Five causes account for nearly every case.

Work through these in order. The first two account for most cases.

Events captured but not delivered

If you skipped tunnelRoute or set it incorrectly in next.config.ts, the Sentry SDK will capture errors in memory but fail to send them due to the Webflow Cloud compatibility date constraint.

Confirm tunnelRoute: "/sentry-tunnel" is set in the withSentryConfig options, redeploy, and test again.

DSN environment variable missing in production

NEXT_PUBLIC_SENTRY_DSN must be added to the Webflow Cloud environment panel. .env.local only applies locally. A missing DSN silently disables the SDK without throwing an error.

Check that the variable is present in Webflow Cloud → Environment Variables, then redeploy.

Source maps are uploaded locally, but stack traces are still minified in production

The source map upload requires SENTRY_AUTH_TOKEN to be set both locally (for manual deploys) and in your CI environment. If the upload succeeds locally but fails in CI, the production deployment has no source maps.

Set the token as a GitHub Actions secret and verify the upload step logs Successfully uploaded N source maps in the deploy output.

Traces showing zero duration for CPU-bound operations

This is expected behavior on Cloudflare Workers. performance.now() and Date.now() only advance after I/O occurs, a security measure to prevent timing attacks. CPU-only spans will always show zero duration.

This isn't a Sentry misconfiguration; it's a Workers platform constraint. I/O-bound operations (database queries, external API calls) trace correctly.

Session Replay is not recording

Session Replay only runs in instrumentation-client.ts, the browser config. Confirm the file exists in your project root, that Sentry initializes without errors in the browser console, and that replaysSessionSampleRate is above 0.

At 0.1, replays are recorded for only 10% of sessions; bump it to 1.0 temporarily if you're testing with low traffic to verify it's working.

What to add after Sentry is running on your Webflow Cloud App

With Sentry running, you have full visibility into every layer of a Webflow Cloud App: browser errors, edge runtime errors from Route Handlers, Server Component failures, and session replays for debugging user-reported issues.

Explore Webflow + Sentry for details on what the Sentry integration covers across the full Webflow ecosystem.