misc(build): build-bundle to share esbuild-plugins (#16876)

Author: paulirish

build/build-bundle-mcp.js

@@ -366,25 +366,7 @@ async function buildBundle(entryPath, distPath) {
           'import.meta': (id) => `{url: '${path.relative(LH_ROOT, id)}'}`,
         }),
       ]),
-      {
-        name: 'postprocess',
-        setup({onEnd}) {
-          onEnd(async (result) => {
-            if (result.errors.length) return;
-            const codeFile = result.outputFiles?.find(file => file.path.endsWith('.js'));
-            const mapFile = result.outputFiles?.find(file => file.path.endsWith('.js.map'));
-            if (!codeFile) throw new Error('missing output');
-
-            const code = codeFile.text;
-            if (code.includes('inflate_fast')) {
-              throw new Error('Expected zlib inflate code to have been removed');
-            }
-
-            await fs.promises.writeFile(codeFile.path, code);
-            if (mapFile) await fs.promises.writeFile(mapFile.path, mapFile.text);
-          });
-        },
-      },
+      plugins.postprocess(),
     ],
   });
 }

build/build-bundle.js

@@ -9,7 +9,6 @@
  * in the browser (as long as they have access to a debugger protocol Connection).
  */
 
-import fs from 'fs';
 import path from 'path';
 import {execSync} from 'child_process';
 import {createRequire} from 'module';
@@ -159,6 +158,10 @@ async function buildBundle(entryPath, distPath, opts = {minify: true}) {
     // Because of page-functions!
     keepNames: true,
     inject: ['./build/process-global.js'],
+    alias: {
+      'debug': require.resolve('debug/src/browser.js'),
+      'lighthouse-logger': require.resolve('../lighthouse-logger/index.js'),
+    },
     /** @type {esbuild.Plugin[]} */
     plugins: [
       plugins.replaceModules({
@@ -203,66 +206,7 @@ async function buildBundle(entryPath, distPath, opts = {minify: true}) {
           'import.meta': (id) => `{url: '${path.relative(LH_ROOT, id)}'}`,
         }),
       ]),
-      {
-        name: 'alias',
-        setup({onResolve}) {
-          onResolve({filter: /\.*/}, (args) => {
-            /** @type {Record<string, string>} */
-            const entries = {
-              'debug': require.resolve('debug/src/browser.js'),
-              'lighthouse-logger': require.resolve('../lighthouse-logger/index.js'),
-            };
-            if (args.path in entries) {
-              return {path: entries[args.path]};
-            }
-          });
-        },
-      },
-      {
-        name: 'postprocess',
-        setup({onEnd}) {
-          onEnd(async (result) => {
-            if (result.errors.length) {
-              return;
-            }
-
-            const codeFile = result.outputFiles?.find(file => file.path.endsWith('.js'));
-            const mapFile = result.outputFiles?.find(file => file.path.endsWith('.js.map'));
-            if (!codeFile) {
-              throw new Error('missing output');
-            }
-
-            // Just make sure the above shimming worked.
-            let code = codeFile.text;
-            if (code.includes('inflate_fast')) {
-              throw new Error('Expected zlib inflate code to have been removed');
-            }
-
-            // Get rid of our extra license comments.
-            // All comments would have been moved to the end of the file, so removing some will not break
-            // source maps.
-            // https://stackoverflow.com/a/35923766
-            const re = /\/\*\*\s*\n([^*]|(\*(?!\/)))*\*\/\n/g;
-            let hasSeenFirst = false;
-            code = code.replace(re, (match) => {
-              if (match.includes('@license') && match.match(/Lighthouse Authors|Google/)) {
-                if (hasSeenFirst) {
-                  return '';
-                }
-
-                hasSeenFirst = true;
-              }
-
-              return match;
-            });
-
-            await fs.promises.writeFile(codeFile.path, code);
-            if (mapFile) {
-              await fs.promises.writeFile(mapFile.path, mapFile.text);
-            }
-          });
-        },
-      },
+      plugins.postprocess({removeExtraLicenses: true}),
     ],
   });
 }

build/build-lightrider-bundles.js

@@ -65,8 +65,22 @@ async function buildStaticServerBundle() {
   });
 }
 
-await Promise.all([
-  buildEntryPoint(),
-  buildReportGenerator(),
-  buildStaticServerBundle(),
-]);
+async function runBuild() {
+  fs.mkdirSync(distDir, {recursive: true});
+  await Promise.all([
+    buildEntryPoint(),
+    buildReportGenerator(),
+    buildStaticServerBundle(),
+  ]);
+}
+
+if (import.meta.main) {
+  await runBuild();
+}
+
+export {
+  buildEntryPoint,
+  buildReportGenerator,
+  buildStaticServerBundle,
+  runBuild,
+};

build/esbuild-plugins.js

@@ -381,11 +381,56 @@ function lighthouseShimPlugin(options) {
   };
 }
 
+/**
+ * @param {{removeExtraLicenses?: boolean}} options
+ * @return {esbuild.Plugin}
+ */
+function postprocess(options = {}) {
+  return {
+    name: 'postprocess',
+    setup({onEnd}) {
+      onEnd(async (result) => {
+        if (result.errors.length) return;
+
+        const codeFile = result.outputFiles?.find(file => file.path.endsWith('.js'));
+        const mapFile = result.outputFiles?.find(file => file.path.endsWith('.js.map'));
+        if (!codeFile) throw new Error('missing output');
+
+        // Just make sure the shimming worked.
+        let code = codeFile.text;
+        if (code.includes('inflate_fast')) {
+          throw new Error('Expected zlib inflate code to have been removed');
+        }
+
+        if (options.removeExtraLicenses) {
+          // Get rid of our extra license comments.
+          // All comments would have been moved to the end of the file, so removing some will not break
+          // source maps.
+          // https://stackoverflow.com/a/35923766
+          const re = /\/\*\*\s*\n([^*]|(\*(?!\/)))*\*\/\n/g;
+          let hasSeenFirst = false;
+          code = code.replace(re, (match) => {
+            if (match.includes('@license') && match.match(/Lighthouse Authors|Google/)) {
+              if (hasSeenFirst) return '';
+              hasSeenFirst = true;
+            }
+            return match;
+          });
+        }
+
+        await fs.promises.writeFile(codeFile.path, code);
+        if (mapFile) await fs.promises.writeFile(mapFile.path, mapFile.text);
+      });
+    },
+  };
+}
+
 export {
   partialLoaders,
   bulkLoader,
   replaceModules,
   ignoreBuiltins,
   umd,
   lighthouseShimPlugin,
+  postprocess,
 };

build/test/build-bundle-test.js

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import path from 'path';
+import fs from 'fs';
+
+import puppeteer from 'puppeteer-core';
+import {getChromePath} from 'chrome-launcher';
+
+import {LH_ROOT} from '../../shared/root.js';
+import {buildBundle} from '../build-bundle.js';
+
+const TEST_HTML = `
+<!DOCTYPE html>
+<html lang="en">
+<head><title>Bundle Test</title></head>
+<body>
+  <h1>Bundle Test Page</h1>
+</body>
+</html>
+`;
+
+describe('Main Bundle build', () => {
+  const bundlePath = `${LH_ROOT}/dist/lighthouse-test-bundle.js`;
+  const entryPath = path.join(LH_ROOT, 'clients/devtools/devtools-entry.js');
+
+  before(async () => {
+    await buildBundle(entryPath, bundlePath, {minify: false});
+  });
+
+  after(() => {
+    if (fs.existsSync(bundlePath)) fs.unlinkSync(bundlePath);
+    if (fs.existsSync(bundlePath + '.map')) fs.unlinkSync(bundlePath + '.map');
+  });
+
+  it('bundle exists', () => {
+    expect(fs.existsSync(bundlePath)).toBe(true);
+  });
+
+  it('bundle can run in a browser', async () => {
+    const browser = await puppeteer.launch({
+      executablePath: getChromePath(),
+    });
+    const page = await browser.newPage();
+    await page.setContent(TEST_HTML, {waitUntil: 'networkidle0'});
+
+    // devtools-entry.js expects `global` to be defined.
+    await page.evaluate(() => {
+      globalThis.global = globalThis;
+    });
+
+    // Inject the bundle
+    await page.addScriptTag({path: bundlePath});
+
+    // Verify Lighthouse is available on the window
+    // devtools-entry.js sets self.snapshot (and others) in worker/non-worker environments.
+    const isLighthouseAvailable = await page.evaluate(() => {
+      // @ts-expect-error
+      return typeof globalThis.snapshot === 'function';
+    });
+
+    await browser.close();
+    expect(isLighthouseAvailable).toBe(true);
+  });
+});

build/test/build-lightrider-bundles-test.js

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import path from 'path';
+import fs from 'fs';
+
+import {LH_ROOT} from '../../shared/root.js';
+import {buildEntryPoint, buildReportGenerator, buildStaticServerBundle} from '../build-lightrider-bundles.js';
+
+describe('Lightrider Bundle builds', () => {
+  const distDir = path.join(LH_ROOT, 'dist', 'lightrider');
+  const lrBundlePath = path.join(distDir, 'lighthouse-lr-bundle.js');
+  const reportGenBundlePath = path.join(distDir, 'report-generator-bundle.js');
+  const staticServerPath = path.join(distDir, 'static-server.js');
+
+  before(async () => {
+    if (!fs.existsSync(distDir)) {
+      fs.mkdirSync(distDir, {recursive: true});
+    }
+  });
+
+  it('builds the LR entry point bundle', async () => {
+    await buildEntryPoint();
+    expect(fs.existsSync(lrBundlePath)).toBe(true);
+    const content = fs.readFileSync(lrBundlePath, 'utf8');
+    expect(content).toContain('Lighthouse');
+  });
+
+  it('builds the report generator bundle', async () => {
+    await buildReportGenerator();
+    expect(fs.existsSync(reportGenBundlePath)).toBe(true);
+    const content = fs.readFileSync(reportGenBundlePath, 'utf8');
+    // UMD bundle for ReportGenerator
+    expect(content).toContain('ReportGenerator');
+  });
+
+  it('builds the static server bundle', async () => {
+    await buildStaticServerBundle();
+    expect(fs.existsSync(staticServerPath)).toBe(true);
+    const content = fs.readFileSync(staticServerPath, 'utf8');
+    expect(content).toContain('module.exports');
+  });
+});