Unverified Commit 39d4f6e6 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 47e4caea
...@@ -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'
...@@ -289,9 +290,27 @@ program ...@@ -289,9 +290,27 @@ program
'--baseline-name <name>', '--baseline-name <name>',
'Name this baseline in the snapshot metadata, overriding branch/sha in the comparison UI.' 'Name this baseline in the snapshot metadata, overriding branch/sha in the comparison UI.'
) )
.addOption(
new Option(
'-o, --output',
'Only write analysis files to disk. Does not start the server.'
).conflicts('query')
)
.addOption(
new Option(
'--query <tool>',
'Query previously generated analyzer data as JSON.'
).conflicts('output')
)
.option(
'--analyze-dir <directory>',
'Analyzer output directory for --query.',
'.next/diagnostics/analyze'
)
.option( .option(
'-o, --output', '--input <json>',
'Only write analysis files to disk. Does not start the server.' 'Tool arguments for --query as a JSON object.',
'{}'
) )
.addOption( .addOption(
new Option( new Option(
...@@ -303,17 +322,27 @@ program ...@@ -303,17 +322,27 @@ program
.default(4000) .default(4000)
.env('PORT') .env('PORT')
) )
.action((directory: string, options: NextAnalyzeOptions) => { .action(
return import('../cli/next-analyze.js') (
.then((mod) => mod.nextAnalyze(options, directory)) directory: string,
.then(() => { options: NextAnalyzeOptions & NextAnalyzeQueryOptions
if (options.output) { ) => {
// The Next.js process is held open by something on the event loop. Exit manually like the `build` command does. if (options.query) {
// TODO: Fix the underlying issue so this is not necessary. return import('../cli/next-analyze-query.js').then((mod) =>
process.exit(0) mod.nextAnalyzeQuery(options.query!, options)
} )
}) }
}) return import('../cli/next-analyze.js')
.then((mod) => mod.nextAnalyze(options, directory))
.then(() => {
if (options.output) {
// The Next.js process is held open by something on the event loop. Exit manually like the `build` command does.
// TODO: Fix the underlying issue so this is not necessary.
process.exit(0)
}
})
}
)
program program
.command('dev', { isDefault: true }) .command('dev', { isDefault: true })
......
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_bundle_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 = {
query?: string
analyzeDir?: string
input?: string
}
function analyzeDir(options: NextAnalyzeQueryOptions): string {
return path.resolve(options.analyzeDir ?? '.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,
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(options),
tool,
input as Record<string, unknown>
)
})
}
...@@ -99,6 +99,19 @@ describe('next experimental-analyze', () => { ...@@ -99,6 +99,19 @@ 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_bundle_overview',
'--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