NextToolbar: una barra de depuración para el App Router de Next.js

NextToolbar es una barra de depuración flotante para el App Router de Next.js. Se queda en la parte inferior de tu app mientras ejecutas next dev y te dice, de un vistazo, qué acaba de pasar en la página que estás viendo.

Por qué existe

Desarrollar con Next.js es hacerte las mismas preguntas todo el día:

• ¿Esta página devolvió un 200, o algo falló en el servidor?
• ¿Esta ruta es estática, o se va a renderizar en cada petición en producción?
• ¿Por qué tardó 800 ms? ¿Fue el render o un fetch lento?
• ¿Ese fetch salió de la caché, o fue a la red cada vez?

Las respuestas existen, pero están repartidas entre la pestaña Network, la terminal de next dev, el indicador de Next y, a veces, un next build solo para salir de dudas. NextToolbar las pone en la propia página, actualizadas en cada navegación.

Qué muestra

• Estado HTTP de la página, en cargas completas y en navegaciones en el cliente.
• La ruta como patrón: /blog/[slug], no solo /blog/hello.
• Modo de render: si la ruta es Static o Dynamic, incluidos los casos en los que el indicador de Next se equivoca.
• Tiempos: render en el servidor, tiempo hasta el primer byte y navegación en el cliente.
• Fetches del servidor con el resultado de la caché (HIT, MISS, SKIP…) y el porcentaje de acierto.
• Errores del cliente y del servidor, con stack trace.
• Profiler de peticiones con resumen, errores, fetches y un timeline del render.
• Server Actions: cada llamada con su estado, tiempo, qué revalidó y adónde redirigió.
• SEO: title, description, canonical, imagen Open Graph y JSON-LD, con lo que falta o está roto.
• Enlaces rotos y seguridad: vulnerabilidades conocidas de tu versión de Next y a cuál actualizar.

Es solo para desarrollo: en un build de producción el componente no renderiza nada.

Instalación

pnpm add -D @angelitolm/next-toolbar

Esta vez sí, como dependencia de desarrollo: nunca se renderiza en producción.

Requisitos: Next.js 15 con App Router y React 19. Para tener todas las funciones necesitas Next 16.3+ con experimental.requestInsights (lo vemos abajo).

Añádela al layout raíz

import { NextToolbar } from '@angelitolm/next-toolbar'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="es">
      <body>
        {children}
        <NextToolbar />
      </body>
    </html>
  )
}

NextToolbar es un client component (el paquete ya incluye 'use client'), así que puedes renderizarlo desde un layout que sea Server Component sin envolverlo. Ponla en el layout raíz para que sobreviva a la navegación entre rutas.

Configuración recomendada

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  // El indicador de Next está abajo a la izquierda y tapa la barra.
  devIndicators: { position: 'top-right' },
  // Solo Next 16.3+: tiempos del servidor, fetches, patrones de ruta y profiler.
  experimental: { requestInsights: true },
}
 
export default nextConfig

Las dos opciones son opcionales. Sin requestInsights (o antes de Next 16.3) la barra sigue mostrando estado, ruta, modo de render, tiempos y errores del cliente y versiones, pero no los tiempos del servidor, los fetches ni el profiler.

La única prop que suele hacer falta es theme: 'system' (por defecto), 'light' o 'dark'.

Que no desaparezca cuando una página falla

Si una página lanza un error y ningún error.tsx lo captura, Next sustituye todo el layout raíz por su página de error, y la barra desaparece con él: justo cuando más la necesitas. Renderízala también en global-error.tsx:

'use client'
import { NextToolbar } from '@angelitolm/next-toolbar'
 
export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
  return (
    <html lang="es">
      <body>
        <h1>Something went wrong</h1>
        <p>{error.digest ?? error.message}</p>
        <NextToolbar />
      </body>
    </html>
  )
}

Así la barra vuelve con el status 500, la petición que falló y su error.

Úsala

Ejecuta pnpm dev y abre cualquier página. La barra aparece a lo largo del borde inferior:

• pasa el ratón por cualquier segmento para ver los detalles;
• haz clic en el id de la petición (# f9b45c) para abrir el profiler;
• haz clic en el logo para minimizarla a un círculo.

Si además usas NextQuery, los dos se coordinan: el panel de NextQuery flota justo encima de la barra en lugar de taparla.

Conclusiones

NextToolbar junta en un solo sitio todo lo que normalmente buscas en cinco: estado, ruta, render, tiempos, caché, errores y SEO. Se instala en dos minutos, no toca producción y te ahorra muchos next build "para ver qué pasa".

Pruébala sin instalar nada en la demo en vivo, lee la documentación o mira el código en GitHub.