Unverified Commit fa0ef04c authored by vercel-fleet-prod[bot]'s avatar vercel-fleet-prod[bot] Committed by GitHub

Add bundle analyzer CLI overview

Co-authored-by: 's avatarWill Binns-Smith <755844+wbinnssmith@users.noreply.github.com>
parent e4579de5
...@@ -29,6 +29,7 @@ import type { NextStartOptions } from '../cli/next-start.js' ...@@ -29,6 +29,7 @@ import type { NextStartOptions } from '../cli/next-start.js'
import type { NextInfoOptions } from '../cli/next-info.js' import type { NextInfoOptions } from '../cli/next-info.js'
import type { NextDevOptions } from '../cli/next-dev.js' import type { NextDevOptions } from '../cli/next-dev.js'
import type { NextAnalyzeOptions } from '../cli/next-analyze.js' import type { NextAnalyzeOptions } from '../cli/next-analyze.js'
import type { NextAnalyzeQueryOptions } from '../cli/next-analyze-query.js'
import type { NextBuildOptions } from '../cli/next-build.js' import type { NextBuildOptions } from '../cli/next-build.js'
import type { NextTypegenOptions } from '../cli/next-typegen.js' import type { NextTypegenOptions } from '../cli/next-typegen.js'
import type { NextPostBuildOptions } from '../cli/next-post-build.js' import type { NextPostBuildOptions } from '../cli/next-post-build.js'
...@@ -279,7 +280,7 @@ program ...@@ -279,7 +280,7 @@ program
}) })
.usage('[directory] [options]') .usage('[directory] [options]')
program const experimentalAnalyzeCommand = program
.command('experimental-analyze') .command('experimental-analyze')
.description( .description(
'Analyze production bundle output with an interactive web ui. Does not produce an application build. Only compatible with Turbopack.' 'Analyze production bundle output with an interactive web ui. Does not produce an application build. Only compatible with Turbopack.'
...@@ -323,6 +324,29 @@ program ...@@ -323,6 +324,29 @@ program
}) })
}) })
experimentalAnalyzeCommand
.command('query')
.description('Query previously generated analyzer data as JSON.')
.argument('<name>', 'Name of the analyzer query to run.')
.argument(
'[directory]',
`The analyzed application directory. ${italic(
'If no directory is provided, the current directory will be used.'
)}`
)
.option('--input <json>', 'Query arguments as a JSON object.', '{}')
.action(
(
name: string,
directory: string | undefined,
options: NextAnalyzeQueryOptions
) => {
return import('../cli/next-analyze-query.js').then((mod) =>
mod.nextAnalyzeQuery(name, directory, options)
)
}
)
program program
.command('dev', { isDefault: true }) .command('dev', { isDefault: true })
.description( .description(
......
import type { AnalyzeData } from '../../shared/lib/analyze-data'
import type { SnapshotMetadata } from './snapshot'
import type { AnalyzeRepository } from './repository'
import z from 'next/dist/compiled/zod'
const DEFAULT_LIMIT = 50
const MAX_LIMIT = 100
const COMPRESSED_CAVEAT =
'Compressed source sizes are estimates because attributed parts are compressed independently.'
type Environment = 'total' | 'client'
type Metric = 'raw' | 'compressed'
interface OverviewArgs {
snapshot?: string
environment?: 'total' | 'client'
metric?: Metric
routeFilter?: string
offset?: number
limit?: number
}
export class AnalyzeQueryError extends Error {
constructor(readonly output: Record<string, unknown>) {
super(
typeof output.error === 'string' ? output.error : 'Analyzer query failed'
)
}
}
function publicError(error: unknown): Record<string, unknown> {
if (!(error instanceof Error))
return { error: 'Unable to query analyzer data' }
if (error.message.startsWith('Unknown snapshot')) {
return { error: 'Unknown snapshot' }
}
if (error.message.startsWith('Unknown route'))
return { error: 'Unknown route' }
if (/^Invalid /.test(error.message)) return { error: error.message }
return { error: 'Unable to query analyzer data' }
}
function safeQuery<T, R>(fn: (args: T) => Promise<R>) {
return async (args: T) => {
try {
return await fn(args)
} catch (error) {
throw new AnalyzeQueryError(publicError(error))
}
}
}
type StoredQuery = {
name: string
execute: (input: unknown) => Promise<unknown>
}
export class AnalyzeQueryRegistry {
constructor(private readonly queries: StoredQuery[]) {}
async execute(name: string, input: unknown): Promise<unknown> {
const query = this.queries.find((item) => item.name === name)
if (!query) {
throw new AnalyzeQueryError({ error: `Unknown analyzer query: ${name}` })
}
try {
return await query.execute(input)
} catch (error) {
if (error instanceof AnalyzeQueryError) throw error
if (error instanceof z.ZodError) {
throw new AnalyzeQueryError({
error: `Invalid arguments for query ${name}: ${error.message}`,
})
}
throw error
}
}
}
function page<T>(values: T[], offset: number, limit: number) {
const result = values.slice(offset, offset + limit)
return {
values: result,
pagination: {
offset,
limit,
total: values.length,
returned: result.length,
truncated: offset + limit < values.length,
},
}
}
function compareText(a: string, b: string): number {
return a < b ? -1 : a > b ? 1 : 0
}
function metricValue(
value: { rawSize: number; compressedSize: number },
metric: Metric
): number {
return metric === 'compressed' ? value.compressedSize : value.rawSize
}
function sourceSizes(
data: AnalyzeData,
sourceIndex: number,
environment: Environment
): { rawSize: number; compressedSize: number } {
let rawSize = 0
let compressedSize = 0
for (const partIndex of data.sourceChunkParts(sourceIndex)) {
const part = data.chunkPart(partIndex)
const output = part && data.outputFile(part.output_file_index)
if (!part || !output) continue
if (
environment !== 'total' &&
(output.filename.startsWith('[client-fs]/') ? 'client' : 'server') !==
environment
) {
continue
}
rawSize += part.size
compressedSize += part.compressed_size
}
return { rawSize, compressedSize }
}
function routeSizes(data: AnalyzeData, environment: Environment) {
let rawSize = 0
let compressedSize = 0
for (let index = 0; index < data.sourceCount(); index++) {
const sizes = sourceSizes(data, index, environment)
rawSize += sizes.rawSize
compressedSize += sizes.compressedSize
}
return { rawSize, compressedSize }
}
function provenance(metadata: SnapshotMetadata) {
return {
id: metadata.id,
createdAt: metadata.createdAt,
baselineName: metadata.baselineName,
nextVersion: metadata.nextVersion,
gitBranch: metadata.gitBranch,
gitSha: metadata.gitSha,
gitDirty: metadata.gitDirty,
routeCount: metadata.routeCount,
}
}
const pagingSchema = {
offset: z.number().int().nonnegative().optional(),
limit: z.number().int().min(1).max(MAX_LIMIT).optional(),
}
const snapshotSchema = z.string().max(100).optional()
const metricSchema = z.enum(['raw', 'compressed']).optional()
export function createAnalyzeQueryRegistry(repository: AnalyzeRepository) {
const queries: StoredQuery[] = []
function registerQuery<T extends z.ZodRawShape>(
name: string,
inputSchema: T,
callback: (args: z.infer<z.ZodObject<T>>) => Promise<unknown>
) {
const schema = z.object(inputSchema).strict()
queries.push({ name, execute: (input) => callback(schema.parse(input)) })
}
registerQuery(
'get_app_overview',
{
snapshot: snapshotSchema,
environment: z.enum(['total', 'client']).optional(),
metric: metricSchema,
routeFilter: z.string().max(1000).optional(),
...pagingSchema,
},
safeQuery(async (args: OverviewArgs) => {
const snapshot = await repository.getSnapshot(args.snapshot)
const snapshots = await repository.listSnapshots()
const environment = args.environment ?? 'total'
const metric = args.metric ?? 'raw'
const filter = args.routeFilter?.toLocaleLowerCase()
const rows = []
for (const route of snapshot.routes) {
if (filter && !route.toLocaleLowerCase().includes(filter)) continue
const sizes = routeSizes(
await repository.loadRoute(args.snapshot, route),
environment
)
rows.push({ route, ...sizes })
}
rows.sort(
(a, b) =>
metricValue(b, metric) - metricValue(a, metric) ||
compareText(a.route, b.route)
)
const paged = page(rows, args.offset ?? 0, args.limit ?? DEFAULT_LIMIT)
return {
snapshot: provenance(snapshot.metadata),
snapshots: {
current: provenance(snapshots.current),
history: snapshots.history.map(provenance),
},
environment,
metric,
resultCounts: {
routesInSnapshot: snapshot.routes.length,
matched: rows.length,
},
routes: paged.values,
pagination: paged.pagination,
caveats: [COMPRESSED_CAVEAT],
}
})
)
return new AnalyzeQueryRegistry(queries)
}
import { AnalyzeRepository } from './repository'
import { AnalyzeQueryError, createAnalyzeQueryRegistry } from './queries'
export { AnalyzeQueryError }
export function queryAnalyzeData(
analyzeDir: string,
name: string,
input: Record<string, unknown>
): Promise<unknown> {
return createAnalyzeQueryRegistry(new AnalyzeRepository(analyzeDir)).execute(
name,
input
)
}
import * as path from 'node:path'
import { readFile } from 'node:fs/promises'
import { AnalyzeData, ModulesData } from '../../shared/lib/analyze-data'
import type { SnapshotMetadata } from './snapshot'
const SNAPSHOT_ID = /^\d{8}-\d{6}-(?:[0-9a-f]{7}|local)$/
const MAX_ROUTE_DATASETS = 8
const MAX_MODULE_DATASETS = 4
const MAX_INDEX_BYTES = 1024 * 1024
const MAX_HISTORY_ENTRIES = 100
interface HistoryIndex {
snapshots: SnapshotMetadata[]
}
export interface SnapshotDataset {
key: string
metadata: SnapshotMetadata
routes: string[]
directory: string
}
function toArrayBuffer(buffer: Buffer): ArrayBuffer {
return buffer.buffer.slice(
buffer.byteOffset,
buffer.byteOffset + buffer.byteLength
) as ArrayBuffer
}
function validateStringArray(value: unknown, label: string): string[] {
if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
throw new Error(`Invalid ${label}`)
}
return value
}
function validateMetadata(value: unknown, label: string): SnapshotMetadata {
const metadata = value as SnapshotMetadata
if (
typeof value !== 'object' ||
value === null ||
typeof metadata.id !== 'string' ||
!SNAPSHOT_ID.test(metadata.id) ||
typeof metadata.createdAt !== 'string' ||
!Number.isFinite(Date.parse(metadata.createdAt)) ||
!Number.isSafeInteger(metadata.routeCount) ||
metadata.routeCount < 0
) {
throw new Error(`Invalid ${label}`)
}
return metadata
}
async function readJson(filename: string, label: string): Promise<unknown> {
const contents = await readFile(filename)
if (contents.byteLength > MAX_INDEX_BYTES) throw new Error(`Invalid ${label}`)
try {
return JSON.parse(contents.toString('utf8'))
} catch {
throw new Error(`Invalid ${label}`)
}
}
function assertInside(base: string, candidate: string): void {
const relative = path.relative(base, candidate)
if (relative.startsWith('..') || path.isAbsolute(relative)) {
throw new Error('Requested analyzer data path is outside its snapshot')
}
}
function validateRoute(route: string): void {
if (
!route.startsWith('/') ||
route.includes('\\') ||
route.includes('\0') ||
route.split('/').some((segment) => segment === '.' || segment === '..')
) {
throw new Error('Invalid route')
}
try {
const decoded = decodeURIComponent(route)
if (
decoded.includes('\\') ||
decoded.includes('\0') ||
decoded.split('/').some((segment) => segment === '.' || segment === '..')
) {
throw new Error('Invalid route')
}
} catch {
throw new Error('Invalid route')
}
}
function insertBounded<T>(
map: Map<string, T>,
key: string,
value: T,
max: number
) {
map.delete(key)
map.set(key, value)
while (map.size > max) {
const oldest = map.keys().next().value
if (oldest === undefined) break
map.delete(oldest)
}
}
export class AnalyzeRepository {
private readonly routeCache = new Map<string, Promise<AnalyzeData>>()
private readonly modulesCache = new Map<string, Promise<ModulesData>>()
constructor(private readonly analyzeDir: string) {}
async listSnapshots(): Promise<{
current: SnapshotMetadata
history: SnapshotMetadata[]
}> {
const current = validateMetadata(
await readJson(
path.join(this.analyzeDir, 'data', 'metadata.json'),
'current snapshot metadata'
),
'current snapshot metadata'
)
let history: SnapshotMetadata[] = []
try {
const parsed = (await readJson(
path.join(this.analyzeDir, 'history', 'history.json'),
'snapshot history'
)) as HistoryIndex
if (
!parsed ||
!Array.isArray(parsed.snapshots) ||
parsed.snapshots.length > MAX_HISTORY_ENTRIES
) {
throw new Error('Invalid snapshot history')
}
history = parsed.snapshots
.map((snapshot, index) =>
validateMetadata(snapshot, `snapshot history entry ${index}`)
)
.sort((a, b) => {
if (a.createdAt !== b.createdAt) {
return a.createdAt < b.createdAt ? 1 : -1
}
return a.id < b.id ? 1 : a.id > b.id ? -1 : 0
})
if (
new Set(history.map((snapshot) => snapshot.id)).size !== history.length
) {
throw new Error('Invalid snapshot history')
}
} catch (error) {
if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
}
return { current, history }
}
async getSnapshot(snapshot = 'current'): Promise<SnapshotDataset> {
const snapshots = await this.listSnapshots()
let metadata: SnapshotMetadata
let directory: string
if (snapshot === 'current') {
metadata = snapshots.current
directory = path.join(this.analyzeDir, 'data')
} else {
if (!SNAPSHOT_ID.test(snapshot))
throw new Error('Invalid snapshot identifier')
const match = snapshots.history.find(
(candidate) => candidate.id === snapshot
)
if (!match) throw new Error(`Unknown snapshot: ${snapshot}`)
metadata = match
directory = path.join(this.analyzeDir, 'history', snapshot)
}
assertInside(this.analyzeDir, directory)
const routes = validateStringArray(
await readJson(path.join(directory, 'routes.json'), 'routes.json'),
'routes.json'
)
for (const route of routes) validateRoute(route)
if (routes.length !== metadata.routeCount) {
throw new Error('Invalid routes.json')
}
return { key: snapshot, metadata, routes, directory }
}
async loadRoute(
snapshot: string | undefined,
route: string
): Promise<AnalyzeData> {
validateRoute(route)
const dataset = await this.getSnapshot(snapshot)
if (!dataset.routes.includes(route))
throw new Error(`Unknown route: ${route}`)
const cacheKey = `${dataset.key}\0${route}`
const cached = this.routeCache.get(cacheKey)
if (cached) {
insertBounded(this.routeCache, cacheKey, cached, MAX_ROUTE_DATASETS)
return cached
}
const filename =
route === '/'
? path.join(dataset.directory, 'analyze.data')
: path.join(
dataset.directory,
...route.slice(1).split('/'),
'analyze.data'
)
assertInside(dataset.directory, filename)
const loading = readFile(filename).then(
(contents) => new AnalyzeData(toArrayBuffer(contents))
)
insertBounded(this.routeCache, cacheKey, loading, MAX_ROUTE_DATASETS)
try {
return await loading
} catch (error) {
this.routeCache.delete(cacheKey)
throw error
}
}
async loadModules(snapshot?: string): Promise<ModulesData> {
const dataset = await this.getSnapshot(snapshot)
const cached = this.modulesCache.get(dataset.key)
if (cached) {
insertBounded(this.modulesCache, dataset.key, cached, MAX_MODULE_DATASETS)
return cached
}
const loading = readFile(path.join(dataset.directory, 'modules.data')).then(
(contents) => new ModulesData(toArrayBuffer(contents))
)
insertBounded(this.modulesCache, dataset.key, loading, MAX_MODULE_DATASETS)
try {
return await loading
} catch (error) {
this.modulesCache.delete(dataset.key)
throw error
}
}
}
#!/usr/bin/env node
import * as path from 'node:path'
import { AnalyzeQueryError, queryAnalyzeData } from '../build/analyze/query'
export type NextAnalyzeQueryOptions = {
input?: string
}
function analyzeDir(directory?: string): string {
return path.resolve(directory ?? '.', '.next/diagnostics/analyze')
}
async function printJson(run: () => Promise<unknown>): Promise<void> {
try {
process.stdout.write(`${JSON.stringify(await run())}\n`)
} catch (error) {
const output =
error instanceof AnalyzeQueryError
? error.output
: {
error:
error instanceof Error ? error.message : 'Analyzer query failed',
}
process.stderr.write(`${JSON.stringify(output)}\n`)
process.exitCode = 1
}
}
export async function nextAnalyzeQuery(
tool: string,
directory: string | undefined,
options: NextAnalyzeQueryOptions
): Promise<void> {
return printJson(async () => {
const input: unknown = JSON.parse(options.input ?? '{}')
if (typeof input !== 'object' || input === null || Array.isArray(input)) {
throw new Error('--input must be a JSON object')
}
return queryAnalyzeData(
analyzeDir(directory),
tool,
input as Record<string, unknown>
)
})
}
...@@ -99,6 +99,20 @@ describe('next experimental-analyze', () => { ...@@ -99,6 +99,20 @@ describe('next experimental-analyze', () => {
) )
const routes = JSON.parse(routesJson) const routes = JSON.parse(routesJson)
expect(routes).toEqual(['/', '/_not-found']) expect(routes).toEqual(['/', '/_not-found'])
const query = await next.runCommand([
'experimental-analyze',
'query',
'get_app_overview',
next.testDir,
'--input',
'{"limit":1}',
])
expect(query.exitCode).toBe(0)
expect(JSON.parse(query.stdout)).toMatchObject({
pagination: { limit: 1, returned: 1 },
routes: [{ route: expect.any(String), rawSize: expect.any(Number) }],
})
}) })
}) })
}) })
......
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