Set up Sentry observability for Next.js runtime paths

.env.example

@@ -19,11 +19,20 @@ WEBHOOK_SECRET=exampleKey
 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=exampleKey
 NEXT_PUBLIC_SUPABASE_ANON_KEY=exampleKey
 NEXT_PUBLIC_SUPABASE_URL="https://bug-free-orbit-rq5vxrpqgv6357w9.github.dev/"
+NEXT_PUBLIC_SENTRY_DSN="https://example.com"
 DIRECT_URL="postgresql://postgres:password@localhost:5432/solar-car-website-next"
+SENTRY_DSN="https://example.com"
+SENTRY_AUTH_TOKEN=exampleKey
+SENTRY_ORG=exampleOrg
+SENTRY_PROJECT=exampleProject
 
+# FLAGS
+FLAGS_SECRET=exampleKey
+# #Local
+FLAGS=exampleKey
 # If you run Postgres locally via `docker-compose up -d`, the example DATABASE_URL
 # and DIRECT_URL above will work as-is. To create a local runtime env file from
 # this example run:
 #
 #   copy .env.example .env    (PowerShell)
-#   cp .env.example .env      (bash/WSL/git-bash)
+#   cp .env.example .env      (bash/WSL/git-bash)

.gitignore

@@ -46,4 +46,6 @@ yarn-error.log*
 .idea
 
 # clerk configuration (can include secrets)
-/.clerk/
+/.clerk/
+# Sentry Config File
+.env.sentry-build-plugin

.vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "Sentry": {
+      "url": "https://mcp.sentry.dev/mcp/calgarysolarcar/javascript-nextjs",
+      "type": "http"
+    }
+  }
+}

instrumentation-client.ts

@@ -0,0 +1,13 @@
+import * as Sentry from "@sentry/nextjs";
+
+const clientTracesSampleRate = Number.parseFloat(
+  process.env.NEXT_PUBLIC_SENTRY_TRACES_SAMPLE_RATE ?? "0.1",
+);
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+  enabled: process.env.NODE_ENV === "production",
+  tracesSampleRate: Number.isNaN(clientTracesSampleRate) ? 0.1 : clientTracesSampleRate,
+});
+
+export const onRouterTransitionStart = Sentry.captureRouterTransitionStart;

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;

next.config.js

@@ -1,3 +1,5 @@
+import { withSentryConfig } from "@sentry/nextjs";
+
 /**
  * Run `build` or `dev` with `SKIP_ENV_VALIDATION` to skip env validation. This is especially useful
  * for Docker builds.
@@ -42,4 +44,30 @@ const config = {
   transpilePackages: ["geist"],
 };
 
-export default config;
+export default withSentryConfig(config, {
+  org: process.env.SENTRY_ORG,
+  project: process.env.SENTRY_PROJECT,
+  silent: !process.env.CI,
+
+  // 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,
+    },
+  },
+
+  widenClientFileUpload: true,
+});

package.json

@@ -22,6 +22,7 @@
     "@clerk/nextjs": "^7.3.5",
     "@flags-sdk/vercel": "1.3.0",
     "@prisma/client": "^6.4.1",
+    "@sentry/nextjs": "10.53.1",
     "@supabase/supabase-js": "^2.45.4",
     "@t3-oss/env-nextjs": "^0.10.1",
     "@tanstack/react-query": "^5.50.0",

sentry.edge.config.ts

@@ -0,0 +1,19 @@
+// 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: process.env.SENTRY_DSN,
+
+  // 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,
+
+  // Define how likely traces are sampled. Adjust this value in production, or use tracesSampler for greater control.
+  tracesSampleRate: 1,
+});

sentry.server.config.ts

@@ -0,0 +1,18 @@
+// 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: process.env.SENTRY_DSN,
+
+  // 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,
+
+  // Define how likely traces are sampled. Adjust this value in production, or use tracesSampler for greater control.
+  tracesSampleRate: 1,
+});

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

@@ -0,0 +1,18 @@
+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/global-error.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import NextError from "next/error";
+import { useEffect } from "react";
+
+import * as Sentry from "@sentry/nextjs";
+
+export default function GlobalError({
+  error,
+}: {
+  error: Error & { digest?: string };
+}) {
+  useEffect(() => {
+    Sentry.captureException(error);
+  }, [error]);
+
+  return (
+    <html lang="en">
+      <body>
+        {/* `NextError` is the default Next.js error page component. Its type
+        definition requires a `statusCode` prop. However, since the App Router
+        does not expose status codes for errors, we simply pass 0 to render a
+        generic error message. */}
+        <NextError statusCode={0} />
+      </body>
+    </html>
+  );
+}

src/app/monitoring/route.ts

@@ -0,0 +1,50 @@
+import { type NextRequest, NextResponse } from "next/server";
+
+// Proxy/tunnel route for Sentry client telemetry. The SDK will POST envelopes
+// to this path when `tunnelRoute` is configured in next.config.js. This
+// implementation forwards the raw envelope to the Sentry ingest endpoint using
+// the server DSN configured in SENTRY_DSN.
+export async function POST(req: NextRequest) {
+  const dsn = process.env.SENTRY_DSN;
+  if (!dsn) {
+    return NextResponse.json(
+      { error: "SENTRY_DSN not configured" },
+      { status: 500 },
+    );
+  }
+
+  // DSN expected like: https://<publicKey>@o4511409386160128.ingest.us.sentry.io/4511409391665152
+  const m = /^https?:\/\/([^@]+)@([^/]+)\/(\d+)(?:\/.*)?$/.exec(dsn);
+  if (!m) {
+    return NextResponse.json({ error: "Invalid SENTRY_DSN" }, { status: 500 });
+  }
+
+  const [, publicKey, host, projectId] = m;
+  const target = `https://${host}/api/${projectId}/envelope/?sentry_key=${publicKey}`;
+
+  try {
+    const body = await req.arrayBuffer();
+    const contentType =
+      req.headers.get("content-type") ?? "application/octet-stream";
+
+    const forwardRes = await fetch(target, {
+      body,
+      headers: {
+        "content-type": contentType,
+      },
+      method: "POST",
+    });
+
+    const text = await forwardRes.text();
+    return new NextResponse(text, { status: forwardRes.status });
+  } catch (err) {
+    return NextResponse.json(
+      { error: "Failed to proxy to Sentry" },
+      { status: 502 },
+    );
+  }
+}
+
+export async function GET() {
+  return NextResponse.json({ ok: true });
+}