bin/route-weight.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1#!/usr/bin/env node
2// The route weight report. Reads a React Router client build's route manifest (build/client/assets/manifest-*.js) and
3// reports, per route that renders a page, the gzip bytes of the JS and CSS a first visit downloads: the client entry and
4// its imports, then every route from root down to this one with its module, imports and stylesheets, each file counted
5// once and gzipped at level 9. Chunks loaded later through import() are not in the manifest and are not counted; nor are
6// fonts and images. Warn-only: a route over the budget, or grown past the baseline, is a ::warning:: line and the run
7// passes. A missing build, a manifest naming a file the build lacks, or a config that is not JSON fails (exit 1): a report
8// that read nothing must not look like a clean one. The table goes to the job summary.
9//
10//   npx devkit-route-weight                     report against .route-weight.json (no file: the report alone)
11//   npx devkit-route-weight --client <dir>      another client build (default build/client)
12//   npx devkit-route-weight --config <file>     another config
13//   npx devkit-route-weight --write-baseline    measure and record each route's total as the config's baseline
14//
15// The config, every field optional:
16//
17//   {
18//     "linked_css": true,
19//     "budget_bytes": 160000,
20//     "growth": { "ratio": 0.05, "bytes": 1024 },
21//     "baseline": { "measured_at": "abc1234", "routes": { "routes/home": 118230 } }
22//   }
23//
24// `linked_css` also counts a stylesheet the counted JS names by URL (a root that links app.css through `?url`). A route
25// grown past its baseline warns when it grew by more than `growth.ratio` of the baseline and more than `growth.bytes`
26// (defaults 0.05 and 1024).
27
28import { execFileSync } from "node:child_process";
29import { appendFileSync, existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
30import { join, resolve } from "node:path";
31import { pathToFileURL } from "node:url";
32import { gzipSync } from "node:zlib";
33
34/**
35 * @typedef {{ id: string, parentId?: string, path?: string, module?: string, imports?: string[], css?: string[],
36 *   hasDefaultExport?: boolean }} ManifestRoute
37 * @typedef {{ entry: { module: string, imports?: string[], css?: string[] }, routes: Record<string, ManifestRoute> }} Manifest
38 * @typedef {{ id: string, path: string, js: number, css: number, total: number }} Row
39 * @typedef {{ linked_css?: boolean, budget_bytes?: number, growth?: { ratio?: number, bytes?: number },
40 *   baseline?: { measured_at?: string, routes?: Record<string, number> } }} Config
41 */
42
43/** The manifest object from the text of manifest-*.js (`window.__reactRouterManifest={...};`). */
44export function parseManifest(/** @type {string} */ text) {
45  return /** @type {Manifest} */ (JSON.parse(text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1)));
46}
47
48/**
49 * One row per route with a default export (a resource route loads no page; root is in every row), heaviest first.
50 * @param {Manifest} manifest
51 * @param {(url: string) => Buffer} read the bytes of a file named as the manifest names it ("/assets/x.js")
52 * @param {(bytes: Buffer) => number} gzip the compressed size
53 * @param {boolean} [linkedCss] also count a stylesheet the counted JS names by URL
54 * @returns {Row[]}
55 */
56export function routeWeights(manifest, read, gzip, linkedCss = false) {
57  /** @type {Map<string, { bytes: Buffer, gzip: number }>} */
58  const files = new Map();
59  const file = (/** @type {string} */ url) => {
60    if (!files.has(url)) {
61      const bytes = read(url);
62      files.set(url, { bytes, gzip: gzip(bytes) });
63    }
64    return /** @type {{ bytes: Buffer, gzip: number }} */ (files.get(url));
65  };
66  const sum = (/** @type {Set<string>} */ urls) => [...urls].reduce((n, url) => n + file(url).gzip, 0);
67  const { entry, routes } = manifest;
68
69  return Object.values(routes)
70    .filter((route) => route.hasDefaultExport && route.id !== "root")
71    .map((route) => {
72      /** @type {ManifestRoute[]} */
73      const chain = [];
74      for (let at = /** @type {ManifestRoute | undefined} */ (route); at; at = at.parentId ? routes[at.parentId] : undefined) chain.unshift(at);
75      const js = new Set([entry.module, ...(entry.imports ?? [])]);
76      const css = new Set(entry.css ?? []);
77      for (const step of chain) {
78        if (step.module) js.add(step.module);
79        for (const url of step.imports ?? []) js.add(url);
80        for (const url of step.css ?? []) css.add(url);
81      }
82      if (linkedCss) for (const url of js) for (const m of file(url).bytes.toString("utf8").matchAll(/\/assets\/[\w.-]+\.css/g)) css.add(m[0]);
83      const path = `/${chain.map((step) => step.path).filter(Boolean).join("/")}`;
84      const [jsBytes, cssBytes] = [sum(js), sum(css)];
85      return { id: route.id, path, js: jsBytes, css: cssBytes, total: jsBytes + cssBytes };
86    })
87    .sort((a, b) => b.total - a.total || a.id.localeCompare(b.id));
88}
89
90/**
91 * A warning per route over the budget or grown past its baseline, and each row's baseline total (null when it has none).
92 * @param {Row[]} rows
93 * @param {Config} config
94 */
95export function check(rows, config) {
96  const { ratio = 0.05, bytes = 1024 } = config.growth ?? {};
97  const base = config.baseline?.routes ?? {};
98  const warnings = [];
99  for (const row of rows) {
100    if (config.budget_bytes !== undefined && row.total > config.budget_bytes) {
101      warnings.push(`${row.id} (${row.path}) loads ${row.total} B gzip, over the budget of ${config.budget_bytes} B.`);
102    }
103    const was = base[row.id];
104    if (was !== undefined && row.total - was > bytes && row.total - was > was * ratio) {
105      warnings.push(`${row.id} (${row.path}) loads ${row.total} B gzip, up ${row.total - was} B from the baseline ${was} B.`);
106    }
107  }
108  return { warnings, baselineOf: (/** @type {string} */ id) => (id in base ? base[id] : null) };
109}
110
111function fail(/** @type {string} */ message) {
112  console.log(`::error::devkit-route-weight: ${message}`);
113  process.exit(1);
114}
115
116function shortHead(/** @type {string} */ root) {
117  try {
118    return execFileSync("git", ["rev-parse", "--short", "HEAD"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
119  } catch {
120    return new Date().toISOString().slice(0, 10);
121  }
122}
123
124function main() {
125  const argv = process.argv.slice(2);
126  const opt = (/** @type {string} */ name, /** @type {string} */ fallback) => (argv.includes(name) && argv[argv.indexOf(name) + 1]) || fallback;
127  const root = process.cwd();
128  const client = resolve(root, opt("--client", join("build", "client")));
129  const file = resolve(root, opt("--config", ".route-weight.json"));
130
131  /** @type {Config} */
132  let config = {};
133  if (existsSync(file)) {
134    try {
135      config = JSON.parse(readFileSync(file, "utf8"));
136    } catch (error) {
137      fail(`${file} is not JSON: ${error instanceof Error ? error.message : String(error)}`);
138    }
139  }
140
141  const assets = join(client, "assets");
142  const manifestFile = existsSync(assets) ? readdirSync(assets).find((name) => /^manifest-[\w-]+\.js$/.test(name)) : undefined;
143  if (!manifestFile) return fail(`no manifest-*.js in ${assets}. Build the app first.`);
144  const read = (/** @type {string} */ url) => {
145    const path = join(client, url.replace(/^\//, ""));
146    if (!existsSync(path)) fail(`the manifest names ${url}, which is not in ${client}.`);
147    return readFileSync(path);
148  };
149  const gzip = (/** @type {Buffer} */ bytes) => gzipSync(bytes, { level: 9 }).length;
150  const rows = routeWeights(parseManifest(readFileSync(join(assets, manifestFile), "utf8")), read, gzip, config.linked_css);
151
152  if (argv.includes("--write-baseline")) {
153    config.baseline = { measured_at: shortHead(root), routes: Object.fromEntries(rows.map((row) => [row.id, row.total])) };
154    writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
155    console.log(`devkit-route-weight: wrote the baseline to ${file}`);
156    return;
157  }
158
159  const all = (/** @type {string} */ ext) => {
160    const names = readdirSync(assets).filter((name) => name.endsWith(ext));
161    return `${names.length} ${ext.slice(1).toUpperCase()} files ${names.reduce((n, name) => n + gzip(readFileSync(join(assets, name))), 0)} B`;
162  };
163  const { warnings, baselineOf } = check(rows, config);
164  const measuredAt = config.baseline?.measured_at;
165  const table = [
166    `### Route weight (gzip bytes, first visit${config.budget_bytes !== undefined ? `, budget ${config.budget_bytes} B` : ""}${measuredAt ? `, baseline ${measuredAt}` : ""})`,
167    "",
168    `Client build: ${all(".js")}, ${all(".css")} gzip.`,
169    "",
170    "| Route | Path | JS | CSS | Total | Baseline |",
171    "|---|---|--:|--:|--:|--:|",
172    ...rows.map((r) => `| ${r.id} | ${r.path} | ${r.js} | ${r.css} | ${r.total} | ${baselineOf(r.id) ?? (measuredAt ? "new" : "")} |`),
173    "",
174    warnings.length ? warnings.map((w) => `- ${w}`).join("\n") : "No route is over its budget or grown past its baseline.",
175  ].join("\n");
176  console.log(table);
177  for (const w of warnings) console.log(`::warning title=Route weight::${w}`);
178  if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${table}\n`);
179}
180
181// Run through node_modules/.bin, argv[1] is the link and import.meta.url the file it points to.
182if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) main();