Dev Overlay

A floating panel that displays logs in real-time during development, with filtering, search, and metrics visualization.

Quick Setup

Add the overlay to your root layout:

typescript

1// app/layout.tsx
2import { VestigDevOverlay } from '@vestig/next/dev'
3 
4export default function RootLayout({ children }: { children: React.ReactNode }) {
5  return (
6    <html>
7      <body>
8        {children}
9        {process.env.NODE_ENV === 'development' && <VestigDevOverlay />}
10      </body>
11    </html>
12  )
13}

The overlay appears as a floating button in the corner of your screen. Click it or press Cmd+L (Mac) / Ctrl+L (Windows/Linux) to toggle the panel.

Configuration

Prop	Type	Default	Description
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	`'bottom-right'`	Position of the toggle button and panel
`endpoint`	`string`	`'/api/vestig/logs'`	SSE endpoint for server log streaming
`toggleKey`	`string`	`'l'`	Keyboard shortcut key (used with Cmd/Ctrl)
`defaultSize`	`{ width: number; height: number }`	`{ width: 500, height: 400 }`	Initial panel dimensions
`defaultOpen`	`boolean`	`false`	Whether to start with the panel open

Features

Real-time Log Streaming

The overlay connects to your server via Server-Sent Events (SSE) to display logs in real-time. Both server-side and client-side logs appear in the same panel.

Filtering & Search

By Level: Filter logs by trace, debug, info, warn, or error
By Namespace: Show logs from specific parts of your app
By Source: Toggle between server, client, or all logs
Search: Full-text search across log messages

Keyboard Shortcuts

Shortcut	Action
`Cmd/Ctrl + L`	Toggle overlay
`Esc`	Close overlay

Metrics Tab

The overlay includes a Metrics tab showing Core Web Vitals (LCP, CLS, INP, TTFB, FCP) when you have VestigMetrics configured.

SSE Endpoint Setup

Create the log streaming endpoint:

typescript

1// app/api/vestig/logs/route.ts
2import { createLogsStreamHandler } from '@vestig/next/dev/api'
3 
4export const GET = createLogsStreamHandler()

Programmatic Access

Using the Log Store

Access the log store directly for custom integrations:

typescript

1import { logStore, useLogStore } from '@vestig/next/dev'
2 
3// Get current logs
4const logs = logStore.getLogs()
5 
6// Subscribe to changes (React hook)
7function MyComponent() {
8  const { logs, isOpen, filters } = useLogStore()
9 
10  return (
11    <div>
12      {logs.map(log => (
13        <div key={log.id}>{log.message}</div>
14      ))}
15    </div>
16  )
17}

Custom Hooks

typescript

1import {
2  useServerLogs,      // Connect to SSE stream
3  useClientLogCapture, // Capture browser logs
4  useDevOverlayShortcuts // Setup keyboard shortcuts
5} from '@vestig/next/dev'
6 
7function CustomOverlay() {
8  // Connect to server logs
9  useServerLogs({ endpoint: '/api/vestig/logs', enabled: true })
10 
11  // Capture console.log, console.error, etc.
12  useClientLogCapture({ enabled: true })
13 
14  // Setup Cmd+L shortcut
15  useDevOverlayShortcuts({ toggleKey: 'l', enabled: true })
16}

Best Practices

1. Development Only

Always wrap the overlay in an environment check:

typescript

1{process.env.NODE_ENV === 'development' && <VestigDevOverlay />}

2. Log Levels

Use appropriate log levels for better filtering:

typescript

1import { createLogger } from 'vestig'
2 
3const log = createLogger({ namespace: 'api' })
4 
5log.trace('Detailed debugging info')  // Hidden by default
6log.debug('Development debugging')    // For dev troubleshooting
7log.info('Normal operations')         // General information
8log.warn('Warning conditions')        // Something unexpected
9log.error('Error conditions')         // Something broke

3. Namespaces

Use namespaces to organize logs and make filtering easier:

typescript

1const dbLog = createLogger({ namespace: 'db' })
2const authLog = createLogger({ namespace: 'auth' })
3const apiLog = createLogger({ namespace: 'api' })

Reconnection Behavior

The overlay automatically reconnects to the SSE stream if the connection drops, using exponential backoff with a maximum of 5 retry attempts.

Next Steps

Web Vitals — Monitor Core Web Vitals in the Metrics tab
Logging Basics — Learn about log levels and namespaces
Server Components — Logging in RSC

Dev Overlay

A floating panel that displays logs in real-time during development, with filtering, search, and metrics visualization.

Quick Setup

Add the overlay to your root layout:

typescript

1// app/layout.tsx
2import { VestigDevOverlay } from '@vestig/next/dev'
3 
4export default function RootLayout({ children }: { children: React.ReactNode }) {
5  return (
6    <html>
7      <body>
8        {children}
9        {process.env.NODE_ENV === 'development' && <VestigDevOverlay />}
10      </body>
11    </html>
12  )
13}

The overlay appears as a floating button in the corner of your screen. Click it or press Cmd+L (Mac) / Ctrl+L (Windows/Linux) to toggle the panel.

Configuration

Prop	Type	Default	Description
`position`	`'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'`	`'bottom-right'`	Position of the toggle button and panel
`endpoint`	`string`	`'/api/vestig/logs'`	SSE endpoint for server log streaming
`toggleKey`	`string`	`'l'`	Keyboard shortcut key (used with Cmd/Ctrl)
`defaultSize`	`{ width: number; height: number }`	`{ width: 500, height: 400 }`	Initial panel dimensions
`defaultOpen`	`boolean`	`false`	Whether to start with the panel open

Features

Real-time Log Streaming

The overlay connects to your server via Server-Sent Events (SSE) to display logs in real-time. Both server-side and client-side logs appear in the same panel.

Filtering & Search

By Level: Filter logs by trace, debug, info, warn, or error
By Namespace: Show logs from specific parts of your app
By Source: Toggle between server, client, or all logs
Search: Full-text search across log messages

Keyboard Shortcuts

Shortcut	Action
`Cmd/Ctrl + L`	Toggle overlay
`Esc`	Close overlay

Metrics Tab

The overlay includes a Metrics tab showing Core Web Vitals (LCP, CLS, INP, TTFB, FCP) when you have VestigMetrics configured.

SSE Endpoint Setup

Create the log streaming endpoint:

typescript

1// app/api/vestig/logs/route.ts
2import { createLogsStreamHandler } from '@vestig/next/dev/api'
3 
4export const GET = createLogsStreamHandler()

Programmatic Access

Using the Log Store

Access the log store directly for custom integrations:

typescript

1import { logStore, useLogStore } from '@vestig/next/dev'
2 
3// Get current logs
4const logs = logStore.getLogs()
5 
6// Subscribe to changes (React hook)
7function MyComponent() {
8  const { logs, isOpen, filters } = useLogStore()
9 
10  return (
11    <div>
12      {logs.map(log => (
13        <div key={log.id}>{log.message}</div>
14      ))}
15    </div>
16  )
17}

Custom Hooks

typescript

1import {
2  useServerLogs,      // Connect to SSE stream
3  useClientLogCapture, // Capture browser logs
4  useDevOverlayShortcuts // Setup keyboard shortcuts
5} from '@vestig/next/dev'
6 
7function CustomOverlay() {
8  // Connect to server logs
9  useServerLogs({ endpoint: '/api/vestig/logs', enabled: true })
10 
11  // Capture console.log, console.error, etc.
12  useClientLogCapture({ enabled: true })
13 
14  // Setup Cmd+L shortcut
15  useDevOverlayShortcuts({ toggleKey: 'l', enabled: true })
16}

Best Practices

1. Development Only

Always wrap the overlay in an environment check:

typescript

1{process.env.NODE_ENV === 'development' && <VestigDevOverlay />}

2. Log Levels

Use appropriate log levels for better filtering:

typescript

1import { createLogger } from 'vestig'
2 
3const log = createLogger({ namespace: 'api' })
4 
5log.trace('Detailed debugging info')  // Hidden by default
6log.debug('Development debugging')    // For dev troubleshooting
7log.info('Normal operations')         // General information
8log.warn('Warning conditions')        // Something unexpected
9log.error('Error conditions')         // Something broke

3. Namespaces

Use namespaces to organize logs and make filtering easier:

typescript

1const dbLog = createLogger({ namespace: 'db' })
2const authLog = createLogger({ namespace: 'auth' })
3const apiLog = createLogger({ namespace: 'api' })

Reconnection Behavior

The overlay automatically reconnects to the SSE stream if the connection drops, using exponential backoff with a maximum of 5 retry attempts.

Next Steps

Web Vitals — Monitor Core Web Vitals in the Metrics tab
Logging Basics — Learn about log levels and namespaces
Server Components — Logging in RSC