Commit a1d376f7 authored by Jude Gao's avatar Jude Gao

add html viewer

parent 1b0083f0
/**
* HTML Report Template for Next.js Insights
*
* Minimal, semantic HTML report with:
* - Collapsible <details> elements for each insight
* - Copy button for pasting into AI agents
* - SSE subscription for real-time updates
* - Fixed-width layout to prevent shift on expand
*/
import type { ReportData } from './insights-report'
import type { Insight } from './insights-types'
/**
* Generate the complete HTML report
* @param data - Report data
* @param ssePort - Port for SSE connection (optional, enables live updates)
*/
export function generateHtmlReport(data: ReportData, ssePort?: number): string {
const sseScript = ssePort
? `
// SSE for real-time updates
const evtSource = new EventSource('http://localhost:${ssePort}/events');
evtSource.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === 'connected') {
console.log('[insights] Connected to server');
return;
}
// New insight received - reload page to show it
// (Simple approach - could be optimized to inject HTML directly)
location.reload();
};
evtSource.onerror = () => {
console.log('[insights] SSE connection lost, will retry...');
};
`
: ''
return `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Next.js Insights Report</title>
<style>
body { max-width: 80ch; margin: 2rem auto; padding: 0 1rem; font-family: system-ui, sans-serif; line-height: 1.5; }
pre { background: #f5f5f5; padding: 1rem; overflow-x: auto; border: 1px solid #ddd; white-space: pre-wrap; word-wrap: break-word; margin: 0; }
code { background: #f5f5f5; padding: 0.1em 0.3em; }
details { margin: 1rem 0; border: 1px solid #ccc; }
summary { padding: 0.75rem; cursor: pointer; background: #fafafa; list-style: none; }
summary::-webkit-details-marker { display: none; }
summary::before { content: '▶ '; font-size: 0.75em; }
details[open] > summary::before { content: '▼ '; }
summary:hover { background: #f0f0f0; }
.insight-content { padding: 0; border-top: 1px solid #ccc; position: relative; }
.copy-btn { position: absolute; top: 0.5rem; right: 0.5rem; font-size: 0.75rem; cursor: pointer; padding: 0.25rem 0.5rem; background: #fff; border: 1px solid #ccc; border-radius: 3px; }
.copy-btn:hover { background: #f0f0f0; }
.severity { font-weight: bold; }
.severity-critical { color: #c00; }
.severity-high { color: #c60; }
.severity-medium { color: #a80; }
.severity-low { color: #080; }
.debug-section { margin: 0; font-size: 0.875rem; border-top: 1px solid #ccc; }
.debug-section summary { background: #f0f0f0; padding: 0.5rem 1rem; }
.debug-section pre { border: none; border-top: 1px solid #ddd; }
hr { margin: 2rem 0; }
.live-badge { background: #0a0; color: #fff; font-size: 0.75rem; padding: 0.2em 0.5em; border-radius: 3px; margin-left: 0.5rem; }
@media (prefers-color-scheme: dark) {
body { background: #111; color: #eee; }
pre, code { background: #222; border-color: #444; }
details { border-color: #444; }
summary { background: #1a1a1a; }
summary:hover { background: #222; }
.insight-content { border-color: #444; }
.copy-btn { background: #222; border-color: #444; color: #eee; }
.copy-btn:hover { background: #333; }
.debug-section { border-color: #444; }
.debug-section summary { background: #222; }
.debug-section pre { border-color: #444; }
}
</style>
</head>
<body>
<header>
<h1>Next.js Insights Report${ssePort ? '<span class="live-badge">LIVE</span>' : ''}</h1>
<p><time datetime="${data.generatedAt}">${new Date(data.generatedAt).toLocaleString()}</time> · Next.js ${data.nextVersion}</p>
</header>
<section>
<h2>Summary</h2>
<ul>
<li><strong>${data.summary.total}</strong> insight(s) detected</li>
<li><strong>${data.summary.bySeverity.critical}</strong> critical, <strong>${data.summary.bySeverity.high}</strong> high, <strong>${data.summary.bySeverity.medium}</strong> medium, <strong>${data.summary.bySeverity.low}</strong> low</li>
<li><strong>${Object.keys(data.summary.byRoute).length}</strong> route(s) affected</li>
</ul>
</section>
<hr>
<main>
<h2>Insights</h2>
${data.insights.length === 0 ? '<p><em>No insights detected yet. Browse your app to trigger waterfall detection.</em></p>' : data.insights.map(renderInsight).join('\n')}
</main>
<hr>
<footer>
<p><small>Learn more at <a href="https://nextjs.org/docs">nextjs.org/docs</a></small></p>
</footer>
<script>
function copyInsight(btn, event) {
event.stopPropagation();
const pre = btn.closest('.insight-content').querySelector('pre');
navigator.clipboard.writeText(pre.textContent).then(() => {
btn.textContent = 'Copied!';
setTimeout(() => btn.textContent = 'Copy', 1500);
});
}
${sseScript}
</script>
</body>
</html>`
}
/**
* Render a single insight
*/
function renderInsight(insight: Insight): string {
const severityClass = `severity-${insight.severity}`
const debugSection = insight.debug
? `
<details class="debug-section">
<summary>Debug Info</summary>
<pre>${escapeHtml(insight.debug)}</pre>
</details>`
: ''
return `
<details>
<summary>
<span class="severity ${severityClass}">[${insight.severity.toUpperCase()}]</span>
${escapeHtml(insight.route)} — ${insight.type}
</summary>
<div class="insight-content">
<button class="copy-btn" onclick="copyInsight(this, event)">Copy</button>
<pre>${escapeHtml(insight.body)}</pre>
${debugSection}
</div>
</details>`
}
/**
* Escape HTML special characters
*/
function escapeHtml(text: string): string {
return text
.replace(/&/g, '&amp;')
.replace(/</g, '&lt;')
.replace(/>/g, '&gt;')
.replace(/"/g, '&quot;')
.replace(/'/g, '&#39;')
}
/**
* Insights Report Generation
*
* Aggregates insights from NDJSON files for the insights server.
*/
import type { Insight, InsightSeverity } from './insights-types'
import { deduplicateInsights } from './insights-storage'
/**
* Summary statistics for a report
*/
export interface ReportSummary {
total: number
bySeverity: Record<InsightSeverity, number>
byType: Record<string, number>
byRoute: Record<string, number>
}
/**
* Complete report data structure
*/
export interface ReportData {
generatedAt: string
nextVersion: string
sessionCount: number
insights: Insight[]
summary: ReportSummary
}
/**
* Aggregate insights and compute summary statistics
*/
export function aggregateInsights(insights: Insight[]): ReportData {
const deduplicated = deduplicateInsights(insights)
// Sort by severity (critical first) then by route
const severityOrder: Record<InsightSeverity, number> = {
critical: 0,
high: 1,
medium: 2,
low: 3,
}
deduplicated.sort((a, b) => {
const severityDiff = severityOrder[a.severity] - severityOrder[b.severity]
if (severityDiff !== 0) return severityDiff
return a.route.localeCompare(b.route)
})
// Compute summary
const summary: ReportSummary = {
total: deduplicated.length,
bySeverity: {
critical: 0,
high: 0,
medium: 0,
low: 0,
},
byType: {},
byRoute: {},
}
for (const insight of deduplicated) {
summary.bySeverity[insight.severity]++
summary.byType[insight.type] = (summary.byType[insight.type] || 0) + 1
summary.byRoute[insight.route] = (summary.byRoute[insight.route] || 0) + 1
}
return {
generatedAt: new Date().toISOString(),
nextVersion: process.env.__NEXT_VERSION || 'unknown',
sessionCount: 1,
insights: deduplicated,
summary,
}
}
/**
* Insights Server
*
* A lightweight HTTP server that:
* - Serves the insights report HTML at the root
* - Provides SSE endpoint for real-time updates
* - Reads accumulated insights from all NDJSON files
*/
import http from 'http'
import type { IncomingMessage, ServerResponse } from 'http'
import { readAllInsights } from './insights-storage'
import { aggregateInsights } from './insights-report'
import { generateHtmlReport } from './insights-report-template'
import type { Insight } from './insights-types'
// Store SSE clients for broadcasting
const sseClients = new Set<ServerResponse>()
// Default port for insights server
const DEFAULT_INSIGHTS_PORT = 3838
/**
* Broadcast a new insight to all connected SSE clients
*/
export function broadcastInsight(insight: Insight): void {
const data = JSON.stringify(insight)
for (const client of sseClients) {
client.write(`data: ${data}\n\n`)
}
}
/**
* Start the insights server
*/
export async function startInsightsServer(
distDir: string,
port: number = DEFAULT_INSIGHTS_PORT
): Promise<{ server: http.Server; port: number }> {
const server = http.createServer(
async (req: IncomingMessage, res: ServerResponse) => {
const url = new URL(req.url || '/', `http://localhost:${port}`)
// SSE endpoint for real-time updates
if (url.pathname === '/events') {
res.writeHead(200, {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache',
Connection: 'keep-alive',
'Access-Control-Allow-Origin': '*',
})
// Send initial ping
res.write('data: {"type":"connected"}\n\n')
// Add to clients
sseClients.add(res)
// Remove on close
req.on('close', () => {
sseClients.delete(res)
})
return
}
// JSON API endpoint
if (url.pathname === '/api/insights') {
try {
const insights = await readAllInsights(distDir, { latestOnly: false })
const reportData = aggregateInsights(insights)
res.writeHead(200, {
'Content-Type': 'application/json',
'Access-Control-Allow-Origin': '*',
})
res.end(JSON.stringify(reportData))
} catch (error) {
res.writeHead(500, { 'Content-Type': 'application/json' })
res.end(JSON.stringify({ error: 'Failed to read insights' }))
}
return
}
// Main HTML page
if (url.pathname === '/' || url.pathname === '/index.html') {
try {
const insights = await readAllInsights(distDir, { latestOnly: false })
const reportData = aggregateInsights(insights)
const html = generateHtmlReport(reportData, port)
res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
res.end(html)
} catch (error) {
res.writeHead(500, { 'Content-Type': 'text/plain' })
res.end('Failed to generate report')
}
return
}
// 404 for other paths
res.writeHead(404, { 'Content-Type': 'text/plain' })
res.end('Not found')
}
)
return new Promise((resolve, reject) => {
server.on('error', (err: NodeJS.ErrnoException) => {
if (err.code === 'EADDRINUSE') {
// Try next port
server.close()
startInsightsServer(distDir, port + 1)
.then(resolve)
.catch(reject)
} else {
reject(err)
}
})
server.listen(port, () => {
resolve({ server, port })
})
})
}
/**
* Insights Storage Module
*
* Handles persistence of insights to NDJSON files during `next start`.
* NDJSON (Newline Delimited JSON) is used because:
* - Append-only (efficient for streaming writes)
* - Stream-friendly (can be read line by line)
* - Works well in Node.js
* - Easily parsed for report generation
*/
import fs from 'fs'
import fsPromises from 'fs/promises'
import path from 'path'
import {
INSIGHTS_DIRECTORY,
INSIGHTS_FILE_PREFIX,
} from '../../shared/lib/constants'
import type { Insight } from './insights-types'
/**
* Generate a session ID based on current timestamp
* Format: YYYY-MM-DDTHH-MM-SS (filesystem-safe ISO format)
*/
export function generateSessionId(): string {
const now = new Date()
return now.toISOString().replace(/[:.]/g, '-').slice(0, 19)
}
/**
* Get the insights directory path within the dist directory
*/
export function getInsightsDirectory(distDir: string): string {
return path.join(distDir, INSIGHTS_DIRECTORY)
}
/**
* Get the full path to an insights NDJSON file
*/
export function getInsightsFilePath(
distDir: string,
sessionId: string
): string {
return path.join(
getInsightsDirectory(distDir),
`${INSIGHTS_FILE_PREFIX}${sessionId}.ndjson`
)
}
/**
* Ensure the insights directory exists
*/
export async function ensureInsightsDirectory(distDir: string): Promise<void> {
const insightsDir = getInsightsDirectory(distDir)
try {
await fsPromises.mkdir(insightsDir, { recursive: true })
} catch (error: any) {
// Ignore if directory already exists
if (error.code !== 'EEXIST') {
throw error
}
}
}
/**
* Synchronously ensure the insights directory exists
*/
export function ensureInsightsDirectorySync(distDir: string): void {
const insightsDir = getInsightsDirectory(distDir)
try {
fs.mkdirSync(insightsDir, { recursive: true })
} catch (error: any) {
// Ignore if directory already exists
if (error.code !== 'EEXIST') {
throw error
}
}
}
/**
* Append a single insight to an NDJSON file
* Creates the file if it doesn't exist
*/
export async function appendInsight(
distDir: string,
sessionId: string,
insight: Insight
): Promise<void> {
await ensureInsightsDirectory(distDir)
const filePath = getInsightsFilePath(distDir, sessionId)
// Append as a single line of JSON followed by newline
const line = JSON.stringify(insight) + '\n'
await fsPromises.appendFile(filePath, line, 'utf-8')
}
/**
* Append multiple insights to an NDJSON file
*/
export async function appendInsights(
distDir: string,
sessionId: string,
insights: Insight[]
): Promise<void> {
if (insights.length === 0) return
await ensureInsightsDirectory(distDir)
const filePath = getInsightsFilePath(distDir, sessionId)
// Build all lines and write at once for efficiency
const lines = insights.map((insight) => JSON.stringify(insight)).join('\n')
await fsPromises.appendFile(filePath, lines + '\n', 'utf-8')
}
/**
* Read all insights from an NDJSON file
*/
export async function readInsightsFile(filePath: string): Promise<Insight[]> {
try {
const content = await fsPromises.readFile(filePath, 'utf-8')
const lines = content.trim().split('\n').filter(Boolean)
return lines
.map((line) => {
try {
return JSON.parse(line) as Insight
} catch {
// Skip malformed lines
return null
}
})
.filter((insight): insight is Insight => insight !== null)
} catch (error: any) {
if (error.code === 'ENOENT') {
return []
}
throw error
}
}
/**
* List all insights files in the insights directory
* Returns files sorted by modification time (newest first)
*/
export async function listInsightsFiles(distDir: string): Promise<string[]> {
const insightsDir = getInsightsDirectory(distDir)
try {
const files = await fsPromises.readdir(insightsDir)
const ndjsonFiles = files.filter(
(file) =>
file.startsWith(INSIGHTS_FILE_PREFIX) && file.endsWith('.ndjson')
)
// Get file stats and sort by modification time
const filesWithStats = await Promise.all(
ndjsonFiles.map(async (file) => {
const fullPath = path.join(insightsDir, file)
const stats = await fsPromises.stat(fullPath)
return { file: fullPath, mtime: stats.mtime.getTime() }
})
)
// Sort by modification time (newest first)
filesWithStats.sort((a, b) => b.mtime - a.mtime)
return filesWithStats.map((f) => f.file)
} catch (error: any) {
if (error.code === 'ENOENT') {
return []
}
throw error
}
}
/**
* Get the most recent insights file
*/
export async function getLatestInsightsFile(
distDir: string
): Promise<string | null> {
const files = await listInsightsFiles(distDir)
return files.length > 0 ? files[0] : null
}
/**
* Read insights from all files (or just the latest)
*/
export async function readAllInsights(
distDir: string,
options: { latestOnly?: boolean } = {}
): Promise<Insight[]> {
const files = await listInsightsFiles(distDir)
if (files.length === 0) {
return []
}
const filesToRead = options.latestOnly ? [files[0]] : files
const allInsights: Insight[] = []
for (const file of filesToRead) {
const insights = await readInsightsFile(file)
allInsights.push(...insights)
}
return allInsights
}
/**
* Deduplicate insights by ID, keeping the most recent
*/
export function deduplicateInsights(insights: Insight[]): Insight[] {
const byId = new Map<string, Insight>()
for (const insight of insights) {
const existing = byId.get(insight.id)
if (
!existing ||
new Date(insight.timestamp) > new Date(existing.timestamp)
) {
byId.set(insight.id, insight)
}
}
return Array.from(byId.values())
}
/**
* Type definitions for Next.js Insights system
*
* Simple structure: metadata + the terminal output as body
*/
/**
* Types of insights that can be detected
*/
export type InsightType = 'waterfall'
/**
* Severity levels for insights
*/
export type InsightSeverity = 'critical' | 'high' | 'medium' | 'low'
/**
* A single insight - simple structure with metadata + body
*/
export interface Insight {
/** Unique identifier for deduplication */
id: string
/** Type of insight */
type: InsightType
/** Severity level */
severity: InsightSeverity
/** Affected route */
route: string
/** ISO timestamp when the insight was detected */
timestamp: string
/** The full terminal output - same as what's logged to console */
body: string
/** Debug info - raw data, thresholds, intermediate calculations */
debug?: string
}
......@@ -273,6 +273,7 @@ export default class NextNodeServer extends BaseServer<
protected internalWaitUntil: WaitUntil | undefined
private isDev: boolean
private sriEnabled: boolean
private insightsSessionId?: string
constructor(options: Options) {
// Initialize super class
......@@ -350,6 +351,37 @@ export default class NextNodeServer extends BaseServer<
})
}
// Initialize insights session for insights builds
// TODO: Only enable for insights builds once we figure out how to persist
// the insights flag from build time to runtime (same issue as ingest endpoint)
if (true) {
const {
generateSessionId,
ensureInsightsDirectorySync,
getInsightsFilePath,
} =
require('./lib/insights-storage') as typeof import('./lib/insights-storage')
const { startInsightsServer } =
require('./lib/insights-server') as typeof import('./lib/insights-server')
this.insightsSessionId = generateSessionId()
ensureInsightsDirectorySync(this.distDir)
const insightsFile = getInsightsFilePath(
this.distDir,
this.insightsSessionId
)
console.log(`[insights] Enabled (writing insights to ${insightsFile})`)
// Start insights server
startInsightsServer(this.distDir)
.then(({ port }) => {
console.log(`[insights] Report available at http://localhost:${port}`)
})
.catch((err) => {
console.error('[insights] Failed to start insights server:', err)
})
}
// when using compile mode static env isn't inlined so we
// need to populate in normal runtime env
if (this.renderOpts.isExperimentalCompile) {
......@@ -1330,7 +1362,8 @@ export default class NextNodeServer extends BaseServer<
report,
this.distDir,
this.dir,
this.nextConfig.cacheComponents ?? false
this.nextConfig.cacheComponents ?? false,
this.insightsSessionId!
)
rawRes.statusCode = 200
rawRes.setHeader('Content-Type', 'application/json')
......
......@@ -205,3 +205,7 @@ export const SYSTEM_ENTRYPOINTS = new Set<string>([
CLIENT_STATIC_FILES_RUNTIME_REACT_REFRESH,
CLIENT_STATIC_FILES_RUNTIME_MAIN_APP,
])
// Insights-related constants
export const INSIGHTS_DIRECTORY = 'insights'
export const INSIGHTS_FILE_PREFIX = 'insights-'
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment