feat: integrate Sentry for error monitoring in Next.js application

- Added Sentry configuration for edge features in `sentry.edge.config.ts`
- Added Sentry configuration for server-side in `sentry.server.config.ts`
- Created a sample API route to demonstrate error tracking in `src/app/api/sentry-example-api/route.ts`
- Developed a frontend page to trigger and log errors in `src/app/sentry-example-page/page.tsx`
- Configured client-side Sentry initialization in `src/instrumentation-client.ts` with Replay integration
- Implemented instrumentation registration logic in `src/instrumentation.ts`

.gitignore

@@ -58,3 +58,6 @@ implementation_plan.md
 # PWA build artifacts (regenerated each build, hashes change)
 public/sw.js
 public/workbox-*.js
+
+# Sentry Config File
+.env.sentry-build-plugin

next.config.ts

@@ -1,3 +1,4 @@
+import { withSentryConfig } from "@sentry/nextjs";
 import type { NextConfig } from "next";
 import { withSerwist } from "@serwist/turbopack";
 
@@ -40,4 +41,40 @@ const nextConfig: NextConfig = {
   },
 };
 
-export default withSerwist(nextConfig);
+export default withSentryConfig(withSerwist(nextConfig), {
+ // For all available options, see:
+ // https://www.npmjs.com/package/@sentry/webpack-plugin#options
+
+ org: "shenzhen-banlv-zhidao-technolo",
+
+ project: "javascript-nextjs",
+
+ // Only print logs for uploading source maps in CI
+ silent: !process.env.CI,
+
+ // For all available options, see:
+ // https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/
+
+ // Upload a larger set of source maps for prettier stack traces (increases build time)
+ widenClientFileUpload: true,
+
+ // Uncomment to route browser requests to Sentry through a Next.js rewrite to circumvent ad-blockers.
+ // This can increase your server load as well as your hosting bill.
+ // Note: Check that the configured route will not match with your Next.js middleware, otherwise reporting of client-
+ // side errors will fail.
+ // tunnelRoute: "/monitoring",
+
+ webpack: {
+   // Enables automatic instrumentation of Vercel Cron Monitors. (Does not yet work with App Router route handlers.)
+   // See the following for more information:
+   // https://docs.sentry.io/product/crons/
+   // https://vercel.com/docs/cron-jobs
+   automaticVercelMonitors: true,
+
+   // Tree-shaking options for reducing bundle size
+   treeshake: {
+     // Automatically tree-shake Sentry logger statements to reduce bundle size
+     removeDebugLogging: true,
+   },
+ },
+});

package.json

@@ -26,6 +26,7 @@
   },
   "dependencies": {
     "@fingerprintjs/fingerprintjs": "^5.2.0",
+    "@sentry/nextjs": "^10.61.0",
     "@stripe/react-stripe-js": "^6.6.0",
     "@stripe/stripe-js": "^9.8.0",
     "@xstate/react": "^5",

sentry.edge.config.ts

@@ -0,0 +1,20 @@
+// This file configures the initialization of Sentry for edge features (middleware, edge routes, and so on).
+// The config you add here will be used whenever one of the edge features is loaded.
+// Note that this config is unrelated to the Vercel Edge Runtime and is also required when running locally.
+// https://docs.sentry.io/platforms/javascript/guides/nextjs/
+
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: "https://a9390ae6d4b06c851854d48b070bb4cf@o4511511166713856.ingest.us.sentry.io/4511612532228096",
+
+  // Define how likely traces are sampled. Adjust this value in production, or use tracesSampler for greater control.
+  tracesSampleRate: 1,
+
+  // Enable logs to be sent to Sentry
+  enableLogs: true,
+
+  // Enable sending user PII (Personally Identifiable Information)
+  // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii
+  sendDefaultPii: true,
+});

sentry.server.config.ts

@@ -0,0 +1,19 @@
+// This file configures the initialization of Sentry on the server.
+// The config you add here will be used whenever the server handles a request.
+// https://docs.sentry.io/platforms/javascript/guides/nextjs/
+
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: "https://a9390ae6d4b06c851854d48b070bb4cf@o4511511166713856.ingest.us.sentry.io/4511612532228096",
+
+  // Define how likely traces are sampled. Adjust this value in production, or use tracesSampler for greater control.
+  tracesSampleRate: 1,
+
+  // Enable logs to be sent to Sentry
+  enableLogs: true,
+
+  // Enable sending user PII (Personally Identifiable Information)
+  // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii
+  sendDefaultPii: true,
+});

src/app/api/sentry-example-api/route.ts

@@ -0,0 +1,17 @@
+import * as Sentry from "@sentry/nextjs";
+export const dynamic = "force-dynamic";
+
+class SentryExampleAPIError extends Error {
+  constructor(message: string | undefined) {
+    super(message);
+    this.name = "SentryExampleAPIError";
+  }
+}
+
+// A faulty API route to test Sentry's error monitoring
+export function GET() {
+  Sentry.logger.info("Sentry example API called");
+  throw new SentryExampleAPIError(
+    "This error is raised on the backend called by the example page.",
+  );
+}

src/app/sentry-example-page/page.tsx

@@ -0,0 +1,237 @@
+"use client";
+
+import * as Sentry from "@sentry/nextjs";
+import Head from "next/head";
+import { useEffect, useState } from "react";
+
+class SentryExampleFrontendError extends Error {
+  constructor(message: string | undefined) {
+    super(message);
+    this.name = "SentryExampleFrontendError";
+  }
+}
+
+export default function Page() {
+  const [hasSentError, setHasSentError] = useState(false);
+  const [isConnected, setIsConnected] = useState(true);
+
+  useEffect(() => {
+    Sentry.logger.info("Sentry example page loaded");
+    async function checkConnectivity() {
+      const result = await Sentry.diagnoseSdkConnectivity();
+      setIsConnected(result !== "sentry-unreachable");
+    }
+    checkConnectivity();
+  }, []);
+
+  return (
+    <div>
+      <Head>
+        <title>sentry-example-page</title>
+        <meta name="description" content="Test Sentry for your Next.js app!" />
+      </Head>
+
+      <main>
+        <div className="flex-spacer" />
+        <svg
+          height="40"
+          width="40"
+          fill="none"
+          xmlns="http://www.w3.org/2000/svg"
+          role="img"
+          aria-label="Sentry logo"
+        >
+          <path
+            d="M21.85 2.995a3.698 3.698 0 0 1 1.353 1.354l16.303 28.278a3.703 3.703 0 0 1-1.354 5.053 3.694 3.694 0 0 1-1.848.496h-3.828a31.149 31.149 0 0 0 0-3.09h3.815a.61.61 0 0 0 .537-.917L20.523 5.893a.61.61 0 0 0-1.057 0l-3.739 6.494a28.948 28.948 0 0 1 9.63 10.453 28.988 28.988 0 0 1 3.499 13.78v1.542h-9.852v-1.544a19.106 19.106 0 0 0-2.182-8.85 19.08 19.08 0 0 0-6.032-6.829l-1.85 3.208a15.377 15.377 0 0 1 6.382 12.484v1.542H3.696A3.694 3.694 0 0 1 0 34.473c0-.648.17-1.286.494-1.849l2.33-4.074a8.562 8.562 0 0 1 2.689 1.536L3.158 34.17a.611.611 0 0 0 .538.917h8.448a12.481 12.481 0 0 0-6.037-9.09l-1.344-.772 4.908-8.545 1.344.77a22.16 22.16 0 0 1 7.705 7.444 22.193 22.193 0 0 1 3.316 10.193h3.699a25.892 25.892 0 0 0-3.811-12.033 25.856 25.856 0 0 0-9.046-8.796l-1.344-.772 5.269-9.136a3.698 3.698 0 0 1 3.2-1.849c.648 0 1.285.17 1.847.495Z"
+            fill="currentcolor"
+          />
+        </svg>
+        <h1>sentry-example-page</h1>
+
+        <p className="description">
+          Click the button below, and view the sample error on the Sentry{" "}
+          <a
+            target="_blank"
+            rel="noopener"
+            href="https://shenzhen-banlv-zhidao-technolo.sentry.io/issues/?project=4511612532228096"
+          >
+            Issues Page
+          </a>
+          . For more details about setting up Sentry,{" "}
+          <a
+            target="_blank"
+            rel="noopener"
+            href="https://docs.sentry.io/platforms/javascript/guides/nextjs/"
+          >
+            read our docs
+          </a>
+          .
+        </p>
+
+        <button
+          type="button"
+          onClick={async () => {
+            Sentry.logger.info("User clicked the button, throwing a sample error");
+            await Sentry.startSpan(
+              {
+                name: "Example Frontend/Backend Span",
+                op: "test",
+              },
+              async () => {
+                const res = await fetch("/api/sentry-example-api");
+                if (!res.ok) {
+                  setHasSentError(true);
+                }
+              },
+            );
+            throw new SentryExampleFrontendError(
+              "This error is raised on the frontend of the example page.",
+            );
+          }}
+          disabled={!isConnected}
+        >
+          <span>Throw Sample Error</span>
+        </button>
+
+        {hasSentError ? (
+          <p className="success">Error sent to Sentry.</p>
+        ) : !isConnected ? (
+          <div className="connectivity-error">
+            <p>
+              It looks like network requests to Sentry are being blocked, which
+              will prevent errors from being captured. Try disabling your
+              ad-blocker to complete the test.
+            </p>
+          </div>
+        ) : (
+          <div className="success_placeholder" />
+        )}
+
+        <div className="flex-spacer" />
+      </main>
+
+      <style>{`
+        main {
+          display: flex;
+          min-height: 100vh;
+          flex-direction: column;
+          justify-content: center;
+          align-items: center;
+          gap: 16px;
+          padding: 16px;
+          font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", sans-serif;
+        }
+
+        h1 {
+          padding: 0px 4px;
+          border-radius: 4px;
+          background-color: rgba(24, 20, 35, 0.03);
+          font-family: monospace;
+          font-size: 20px;
+          line-height: 1.2;
+        }
+
+        p {
+          margin: 0;
+          font-size: 20px;
+        }
+
+        a {
+          color: #6341F0;
+          text-decoration: underline;
+          cursor: pointer;
+
+          @media (prefers-color-scheme: dark) {
+            color: #B3A1FF;
+          }
+        }
+
+        button {
+          border-radius: 8px;
+          color: white;
+          cursor: pointer;
+          background-color: #553DB8;
+          border: none;
+          padding: 0;
+          margin-top: 4px;
+
+          & > span {
+            display: inline-block;
+            padding: 12px 16px;
+            border-radius: inherit;
+            font-size: 20px;
+            font-weight: bold;
+            line-height: 1;
+            background-color: #7553FF;
+            border: 1px solid #553DB8;
+            transform: translateY(-4px);
+          }
+
+          &:hover > span {
+            transform: translateY(-8px);
+          }
+
+          &:active > span {
+            transform: translateY(0);
+          }
+
+          &:disabled {
+	            cursor: not-allowed;
+	            opacity: 0.6;
+
+	            & > span {
+	              transform: translateY(0);
+	              border: none
+	            }
+	          }
+        }
+
+        .description {
+          text-align: center;
+          color: #6E6C75;
+          max-width: 500px;
+          line-height: 1.5;
+          font-size: 20px;
+
+          @media (prefers-color-scheme: dark) {
+            color: #A49FB5;
+          }
+        }
+
+        .flex-spacer {
+          flex: 1;
+        }
+
+        .success {
+          padding: 12px 16px;
+          border-radius: 8px;
+          font-size: 20px;
+          line-height: 1;
+          background-color: #00F261;
+          border: 1px solid #00BF4D;
+          color: #181423;
+        }
+
+        .success_placeholder {
+          height: 46px;
+        }
+
+        .connectivity-error {
+          padding: 12px 16px;
+          background-color: #E50045;
+          border-radius: 8px;
+          width: 500px;
+          color: #FFFFFF;
+          border: 1px solid #A80033;
+          text-align: center;
+          margin: 0;
+        }
+
+        .connectivity-error a {
+          color: #FFFFFF;
+          text-decoration: underline;
+        }
+      `}</style>
+    </div>
+  );
+}

src/instrumentation-client.ts

@@ -0,0 +1,31 @@
+// This file configures the initialization of Sentry on the client.
+// The added config here will be used whenever a users loads a page in their browser.
+// https://docs.sentry.io/platforms/javascript/guides/nextjs/
+
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: "https://a9390ae6d4b06c851854d48b070bb4cf@o4511511166713856.ingest.us.sentry.io/4511612532228096",
+
+  // Add optional integrations for additional features
+  integrations: [Sentry.replayIntegration()],
+
+  // Define how likely traces are sampled. Adjust this value in production, or use tracesSampler for greater control.
+  tracesSampleRate: 1,
+  // Enable logs to be sent to Sentry
+  enableLogs: true,
+
+  // Define how likely Replay events are sampled.
+  // This sets the sample rate to be 10%. You may want this to be 100% while
+  // in development and sample at a lower rate in production
+  replaysSessionSampleRate: 0.1,
+
+  // Define how likely Replay events are sampled when an error occurs.
+  replaysOnErrorSampleRate: 1.0,
+
+  // Enable sending user PII (Personally Identifiable Information)
+  // https://docs.sentry.io/platforms/javascript/guides/nextjs/configuration/options/#sendDefaultPii
+  sendDefaultPii: true,
+});
+
+export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

src/instrumentation.ts

@@ -0,0 +1,13 @@
+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");
+  }
+}
+
+export const onRequestError = Sentry.captureRequestError;