How do I sign up for Sentry and set up a Next.js project using `npx @sentry/wizard@latest -i nextjs`?

To go from “I’ve heard of Sentry” to “Sentry is capturing Next.js errors and performance data in my project,” you need to do two things: create a Sentry account/org, then run the Next.js wizard (npx @sentry/wizard@latest -i nextjs) against your app and confirm events are flowing.

Quick Answer: You sign up for Sentry at sentry.io, create a project (pick “Next.js”), then run npx @sentry/wizard@latest -i nextjs in your Next.js app directory. The wizard installs the SDK, wires up error monitoring and tracing, and leaves you with a configured project that sends exceptions and transactions to Sentry.

---

The Quick Overview

• What It Is: A guided setup flow that connects a new (or existing) Next.js app to Sentry using the @sentry/nextjs SDK and the Sentry Wizard.
• Who It Is For: Next.js developers who want code-level visibility into production errors, slow requests, and user-impacting issues without manually wiring every piece.
• Core Problem Solved: It removes the guesswork from instrumenting Next.js: you don’t have to hand-edit every config file or wonder if errors and traces are actually being captured.

---

Step 1: Sign up for Sentry

Before you run any CLI, you need an organization and project in Sentry.

1. Create your Sentry account

   • Go to https://sentry.io.
   • Click Get Started (or Try Sentry for free).
   • Sign up with email, GitHub, GitLab, or other supported SSO.
   • Create or join an organization (this is your top-level workspace).

2. Create a Next.js project in Sentry

   • After onboarding, click Projects → Create Project.
   • Choose Next.js (or “JavaScript / Browser” → Next.js) as the platform.
   • Give it a name like my-nextjs-app.
   • Sentry will show you a DSN and framework-specific steps. Keep this tab open; the wizard will wire this DSN into your code automatically.

3. Confirm your data region and security posture (optional but smart)

   • When you set up your org, choose your data residency (United States or Germany).
   • Sentry runs on Google Cloud Platform, encrypts data with TLS in transit and AES‑256 at rest, and maintains SOC 2 Type II, ISO 27001, and HIPAA attestation.
   • On Business+ you can add SAML SSO, SCIM, and governance controls if you’re rolling this out for a larger team.

Now you’ve got a Sentry org and an empty Next.js project ready to receive events.

---

Step 2: Prepare your Next.js project

Move into your Next.js app root:

cd path/to/your-nextjs-app

Make sure:

• You’re on Node 16+ (or whatever your Next.js version requires).
• You have a package manager installed (npm, yarn, or pnpm).
• You can successfully run next dev before adding Sentry, so if something breaks later you know it’s config, not your base app.

If you don’t have a project yet, you can create one quickly:

npx create-next-app@latest my-nextjs-app
cd my-nextjs-app

---

Step 3: Run the Sentry Wizard for Next.js

This is where npx @sentry/wizard@latest -i nextjs comes in.

From your Next.js project directory, run:

npx @sentry/wizard@latest -i nextjs

What the wizard does

The Sentry Wizard is an interactive CLI that:

• Installs the @sentry/nextjs SDK and any needed dependencies.
• Creates or updates config files to hook Sentry into:
  • API routes and server-side code (capturing thrown errors).
  • Client-side pages and components (capturing React errors).
• Wires up tracing so you get transactions and spans for requests, page loads, and route transitions.
• Adds a Sentry config file that points to your project’s DSN.
• Optionally adds source map support so stack traces are symbolicated back to your original TypeScript or minified code.

Typical wizard flow

You’ll see prompts like:

1. Which Sentry organization?
   • If you’re logged in via browser, the wizard can list your orgs.
2. Which Sentry project?
   • Select the Next.js project you created earlier.
3. Confirm package manager
   • It will detect npm, yarn, or pnpm and run the right install command.
4. Enable performance monitoring and Session Replay?
   • You can start with just errors, or capture more telemetry. I recommend enabling tracing at minimum so you can debug slowdowns, not just crashes.

When it finishes, the wizard prints a summary of changes. Skim this; it’s a quick map of what just got wired up.

---

Step 4: Understand what changed in your Next.js app

The exact files may differ by Next.js version (pages router vs app router), but you’ll typically see:

1. Sentry config files

   • sentry.client.config.ts / .js
   • sentry.server.config.ts / .js
   • These call Sentry.init({...}) with:
     • dsn (your project connection string)
     • environment (e.g., development, production)
     • tracesSampleRate or tracesSampler for performance monitoring
   • You can tweak these settings later, e.g., lower tracesSampleRate in production.

2. Next.js config integration

   • next.config.js updated to wrap your config with withSentryConfig:

     const { withSentryConfig } = require('@sentry/nextjs');
     
     const nextConfig = {
       // your existing config
     };
     
     module.exports = withSentryConfig(nextConfig, {
       // Sentry build-time options
     });
     

   • This enables Sentry’s build-time magic like source map upload.

3. Error instrumentation wiring

   • For the pages router:
     • _error.js or _app.js may be wrapped to ensure client errors are captured.
   • For the app router:
     • The wizard may add or update error.tsx boundaries to capture React server component errors and client errors with Sentry.

4. Source map and bundling config

   • The wizard configures Sentry to upload source maps during build so you see original code in stack traces instead of minified bundles.

If you’re curious (and you should be), commit your repo before running the wizard, then run a diff after. That’s the easiest way to see every change.

---

Step 5: Verify Sentry is capturing events

Before trusting this in production, trigger some noise.

1. Run the dev server

npm run dev
# or
yarn dev
# or
pnpm dev

2. Trigger a test error

Pick a page and add a deliberate throw:

// e.g., in pages/index.tsx or app/page.tsx
export default function Home() {
  if (typeof window !== 'undefined') {
    throw new Error('Sentry Next.js test error');
  }

  return <div>Hello from Next.js</div>;
}

Refresh the page in your browser. You’ll see the error locally (as you should), and Sentry should capture it.

3. Confirm in Sentry

• Go to your Sentry project.
• Within a few seconds, you should see a new issue called something like Error: Sentry Next.js test error.
• Open it to see:
  • Stack trace with your original file/line if source maps are enabled.
  • Tags (environment, release, browser, URL, etc.).
  • Breadcrumbs and relevant context.

Once you’re satisfied, remove the test error from your code.

---

Step 6: Enable performance monitoring for Next.js

Errors are only half the story. You also want to know when pages or API routes are slow.

The wizard typically sets a default tracesSampleRate. You’ll see this in sentry.client.config and/or sentry.server.config:

import * as Sentry from '@sentry/nextjs';

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0, // capture 100% of transactions (tune this in prod)
});

Recommendations:

• In development, tracesSampleRate: 1.0 is fine.
• In production, start with 0.1–0.3 depending on your traffic and budget, then adjust:

  tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.2 : 1.0,
  

• For fine-grained control at scale, use tracesSampler to sample based on route, user, or environment.

Once deployed, you’ll see transactions and spans in Sentry:

• Each page view or API request shows up as a transaction.
• Inside, spans show:
  • Rendering time
  • Data fetching spans (getServerSideProps, route handlers, etc.)
  • Downstream calls (DB, HTTP, etc.), if instrumented

This is where you can “trace through services (for instance, frontend to backend) to identify poor-performing code” when you also instrument your backend with Sentry.

---

Step 7: Use logs, Session Replay, and Seer for full context (optional but powerful)

The basic wizard gets errors and performance. From there, you can layer on more context.

Session Replay

• Add Session Replay (if you enabled it in the wizard or later) to see what the user actually did before an error.
• This lets you connect “what users experienced” (a broken click or weird UI state) with “where in the code it failed.”

Logs and Profiling

• Use Sentry Logs to bring structured logs next to errors and transactions.
• Add Profiling to see CPU hotspots when requests or renders are slow.

Seer (AI-assisted debugging)

If you use Seer, Sentry’s AI debugging add-on:

• Seer consumes:
  • Stack traces
  • Spans from tracing
  • Commits (Suspect Commits)
  • Logs and profiling data
• It can:
  • Identify likely root causes
  • Propose fixes
  • Even open pull requests for you
• Seer is purchased as an add-on, priced per active contributor, not per event.

This turns “we saw an error in Next.js” into “here’s why it broke and a proposed patch,” without leaving Sentry.

---

What npx @sentry/wizard@latest -i nextjs doesn’t do (and what you still own)

The wizard is opinionated and saves you time, but it’s not magic.

• It doesn’t:

  • Decide your sampling strategy for you; you should set tracesSampleRate/tracesSampler based on traffic and cost.
  • Configure alert rules automatically.
  • Set up code ownership rules for your team.

• You still need to:

  • Configure Ownership Rules / Code Owners so issues route to the right people.
  • Set alerts for:
    • New issue types
    • Regression of previously fixed errors
    • Performance regressions (e.g., API route p95 latency spikes)
  • Integrate with your tools (GitHub, GitLab, Slack, Linear, Jira, etc.) so Sentry issues become tracked work.

This is how you go from “we have data” to “we have a debugging workflow.”

---

Example: A minimal end-to-end workflow

To make this concrete, here’s how I usually instrument and verify a new Next.js service with a team:

1. Day 0
   • Sign up at sentry.io, create org + Next.js project.
   • Run npx @sentry/wizard@latest -i nextjs.
   • Commit the wizard changes to Git.
2. Day 1
   • Deploy to a non-prod environment (staging).
   • Trigger test errors and slow requests.
   • Verify:
     • Errors show up as grouped issues.
     • Transactions and spans show server render times, route handlers, and external calls.
   • Add a simple alert: “Notify Slack when a new issue occurs in environment:production.”
3. Day 2+
   • Roll to production.
   • Tune sampling and alert thresholds based on traffic.
   • Add Ownership Rules so frontend errors go to the frontend team, API route errors go to backend owners.
   • Optionally enable Seer to shorten “triage → root cause → fix” cycles.

---

Summary

To sign up for Sentry and set up a Next.js project using npx @sentry/wizard@latest -i nextjs, you:

1. Create a Sentry account and organization at sentry.io.
2. Add a Next.js project and note the DSN.
3. From your Next.js app directory, run:

   npx @sentry/wizard@latest -i nextjs
   

4. Let the wizard install @sentry/nextjs, update configs, and wire up error and performance monitoring.
5. Trigger a test error and confirm issues appear in Sentry.
6. Tune tracing, alerts, and ownership so incidents reach the right people with the right context.

You end up with a Next.js app that doesn’t just fail loudly—it tells you where, why, and what changed so you can fix it faster.

---

Next Step

Get Started