How to Debug Rendering and Performance Issues Using Astro's Built-In Tools

Astro provides first-class debugging capabilities through Vite's dev overlay, the ASTRO_DEBUG environment variable for SSR timing, the --analyze flag for bundle visualization, and built-in hydration warnings—all without requiring external dependencies.

When building static and server-rendered applications with the withastro/astro framework, identifying bottlenecks requires deep visibility into both the build process and runtime behavior. Fortunately, Astro ships with comprehensive debugging tools that leverage its Vite-powered development server to help you debug rendering and performance issues using Astro's built-in tools without installing additional packages.

Essential Debugging Tools Overview

Astro categorizes its debugging capabilities by the type of issue you're investigating. Each tool targets specific rendering or performance concerns:

Component Rendering Errors

The dev overlay (Vite error overlay) provides full stack traces, source file links, and a "Show component source" button directly in your browser when compilation fails.

Client-Side Hydration Problems

The astro dev console automatically warns about missing client:* directives, mismatched IDs, and hydration mismatches between server and client renders.

Bundle Size Analysis

The astro build --analyze command generates an interactive treemap visualization (similar to webpack-bundle-analyzer) showing exactly which modules contribute to JavaScript bloat.

Server-Side Rendering Performance

Setting ASTRO_DEBUG=true during development enables detailed timing logs for each route and component render, helping identify slow Astro components.

Production Performance Auditing

The astro preview --open command starts a production-like server that allows you to run Chrome DevTools Lighthouse audits against real-world Core Web Vitals metrics.

Core Implementation Architecture

Understanding where these features live in the Astro source code helps you interpret their output and contribute fixes when needed.

Dev Overlay Implementation

The browser error overlay is implemented in packages/astro/src/core/dev/devOverlay.ts. This module listens for Vite compile errors, formats them for readability, and injects the overlay script into HTML responses. When you see a red error screen in development, this file is generating that UI.

SSR Timing and Debug Logs

Server-side render timing is handled by packages/astro/src/runtime/server/dev/timing.ts. This file wraps each render call with performance.now() to measure execution time, aggregates per-route statistics, and writes formatted logs to your terminal when the ASTRO_DEBUG environment variable is set.

Bundle Analysis Integration

The --analyze flag logic resides in packages/astro/src/cli/commands/build.ts. After Vite completes the production build, this command forks into rollup-plugin-visualizer to generate the dist/stats.html file containing the interactive bundle size treemap.

Hydration Warning System

Client-side hydration diagnostics are emitted from packages/astro/src/runtime/client/hydration.ts. This module detects when components are rendered on the server but lack matching client:* directives on the client, printing console warnings that help you fix hydration mismatches.

Preview Server for Auditing

The production preview server is implemented in packages/astro/src/cli/commands/preview.ts. This starts a minimal static server that mirrors your production environment exactly, enabling you to run Lighthouse audits and test Core Web Vitals like CLS, LCP, and FID before deployment.

Practical Debugging Commands

These specific command patterns help you debug rendering and performance issues using Astro's built-in tools in real-world scenarios.

Basic Development with Error Overlay

Start the dev server to get instant feedback on compilation errors:

npm run astro dev

When errors occur, the browser displays a red overlay with full stack traces. Click the Source link to jump directly to the offending file.

Detailed SSR Performance Timing

Enable debug logging to identify slow components during server-side rendering:

ASTRO_DEBUG=true npm run astro dev

Console output example:

→ /src/pages/index.astro rendered in 12.4 ms
→ Component Header (src/components/Header.astro) rendered in 3.1 ms
→ Total route time: 18.9 ms

Bundle Size Analysis

Analyze JavaScript bloat after building:

npm run astro build -- --analyze

This generates dist/stats.html with an interactive treemap. Hover over blocks to see which components or libraries contribute most to the payload.

Hydration Mismatch Detection

The dev server automatically warns about hydration issues:

[astro] Hydration mismatch: Component `Carousel` rendered on the server but has no matching `client:*` directive.

Fix by adding the appropriate directive:

<Carousel client:load />

Production Performance Auditing

Test real-world performance before deployment:

npm run astro preview -- --open

This opens your production build at http://localhost:4321. Use Chrome DevTools Lighthouse to audit Core Web Vitals including CLS, LCP, and FID.

Pro Tip: When the bundle analyzer shows large third-party chunks, use the client:only directive to keep heavy libraries out of the server bundle while still loading them client-side:

<HeavyChartingLibrary client:only="react" />

Summary

• Start with astro dev to leverage Vite's error overlay for immediate feedback on compilation and rendering errors.
• Enable ASTRO_DEBUG=true to capture detailed server-side render timing for each route and component.
• Run astro build --analyze to visualize bundle composition and identify JavaScript bloat sources.
• Monitor console warnings during development to catch hydration mismatches early and fix them with proper client:* directives.
• Use astro preview to run Lighthouse audits against production-like builds before deploying.

Frequently Asked Questions

How do I enable debug mode in Astro?

Set the ASTRO_DEBUG environment variable to true when starting the dev server:

ASTRO_DEBUG=true npm run astro dev

This activates detailed logging in packages/astro/src/runtime/server/dev/timing.ts, showing precise render times for each route and component in your terminal.

What is the Astro dev overlay?

The dev overlay is a browser-based error interface implemented in packages/astro/src/core/dev/devOverlay.ts. It intercepts Vite compilation errors and renders a full-screen overlay with stack traces, source file links, and a "Show component source" button, allowing you to click directly into the offending code.

How can I analyze my Astro bundle size?

Run the build command with the --analyze flag:

npm run astro build -- --analyze

This generates dist/stats.html using logic from packages/astro/src/cli/commands/build.ts and rollup-plugin-visualizer. The interactive treemap reveals which components or third-party libraries contribute most to your JavaScript payload.

Why am I seeing hydration mismatch warnings?

Hydration warnings originate from packages/astro/src/runtime/client/hydration.ts when a component is rendered on the server but lacks a corresponding client:* directive on the client. This indicates that Astro expected to hydrate interactive elements but couldn't find the matching client-side instructions. Resolve these by adding the appropriate hydration directive, such as client:load or client:only, to your component tags.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}