Next.js Debugging Tips for Faster Development

Next.js Debugging Tips for Faster Development

Next.js blurs the line between server and client, making debugging tricky. Here are tips for each layer.

Debug Server Components

Server Components run on the server, so console.log output appears in your terminal, not the browser:

// This logs to your terminal
export default async function Page() {
  const data = await fetchData();
  console.log('Server data:', data); // Terminal output
  return <div>{data.title}</div>;
}

For breakpoint debugging, use Node.js inspector:

NODE_OPTIONS='--inspect' next dev

Then open chrome://inspect in Chrome.

Fix Hydration Mismatches

Hydration errors are the most common Next.js issue. They happen when server HTML doesn't match client render:

// Bad: different output on server vs client
export default function Page() {
  return <p>Current time: {new Date().toLocaleString()}</p>
}

// Good: use useEffect for client-only values
export default function Page() {
  const [time, setTime] = useState<string>();
  useEffect(() => setTime(new Date().toLocaleString()), []);
  return <p>Current time: {time ?? 'Loading...'}</p>
}

Common causes: browser extensions injecting elements, date/time formatting, window/localStorage access during render.

Debug API Routes

// app/api/users/route.ts
export async function GET(request: Request) {
  console.log('Headers:', Object.fromEntries(request.headers));
  console.log('URL:', request.url);

  try {
    const users = await db.user.findMany();
    return Response.json(users);
  } catch (error) {
    console.error('API error:', error);
    return Response.json({ error: 'Failed to fetch' }, { status: 500 });
  }
}

Debug Build Issues

# Verbose build output
next build --debug

# Analyze bundle size
npx @next/bundle-analyzer

Common Pitfalls

• "use client" missing — interactive components need the directive
• Importing server-only code in client components — use server-only package
• Dynamic imports — use next/dynamic with ssr: false for client-only libraries

For production Next.js apps, Bugsly captures both server-side and client-side errors with full context, including which component failed and the request that triggered it.