@code-pushup/lighthouse-plugin 0.51.0 → 0.53.0

package/README.md

@@ -119,24 +119,27 @@ export default {
 
 ## Flags
 
-The plugin accepts a second optional argument, `flags`.
+The plugin accepts an optional second argument, `flags`.
 
-`flags` is the Lighthouse [CLI flags](https://github.com/GoogleChrome/lighthouse/blob/7d80178c37a1b600ea8f092fc0b098029799a659/cli/cli-flags.js#L80) as a JS object.
+`flags` is a JavaScript object containing Lighthouse [CLI flags](https://github.com/GoogleChrome/lighthouse/blob/7d80178c37a1b600ea8f092fc0b098029799a659/cli/cli-flags.js#L80).
 
-Within the flags object a couple of other external configuration files can be referenced. E.g. `configPath` , `preset` or `budgetPath` reference external `json` or JavaScript files.
+Within the `flags` object, external configuration files can be referenced using options like `configPath` , `preset`, or `budgetPath`. These options allow Lighthouse to load custom configurations, audit presets, or performance budgets from external `json` or JavaScript files.
 
-For a complete list the [official documentation of CLI flags](https://github.com/GoogleChrome/lighthouse/blob/main/readme.md#cli-options)
+For a complete list of available options, refer to [the official Lighthouse documentation](https://github.com/GoogleChrome/lighthouse/blob/main/readme.md#cli-options).
 
 > [!TIP]  
-> If you are not used to work with the Lighthouse CLI you would pass flags like this:
+> If you are new to working with the Lighthouse CLI, flags can be passed like this:
 > `lighthouse https://example.com --output=json --chromeFlags='--headless=shell'`
 >
-> Now with the plugin it would look like this:
+> With the plugin, the configuration would be:
 >
 > ```ts
 > // code-pushup.config.ts
 > ...
-> lighthousePlugin('https://example.com', { output: 'json', chromeFlags: ['--headless=shell']});
+> lighthousePlugin('https://example.com', {
+>   output: 'json',
+>   chromeFlags: ['--headless=shell'],
+> });
 > ```
 
 > [!note]
@@ -149,14 +152,47 @@ For a complete list the [official documentation of CLI flags](https://github.com
 
 ## Chrome Flags for Tooling
 
-We recommend using Chrome flags for more stable runs in a tooling environment.
-The [`chrome-launcher`](https://www.npmjs.com/package/chrome-launcher) package provides a set of flags dedicated to tooling that they also documented very well.
+We recommend using Chrome flags for more stable runs in a tooling environment. The [`chrome-launcher`](https://www.npmjs.com/package/chrome-launcher) package offers a well-documented set of flags specifically designed to ensure reliable execution.
+
+The latest version of `@code-pushup/lighthouse-plugin` provides `DEFAULT_CHROME_FLAGS`, a pre-configured constant that includes Chrome’s default flags for stable, headless execution out of the box. This means you do not need to specify `chromeFlags` manually unless you want to modify them.
+
+### Default Usage
+
+If no `chromeFlags` are provided, the plugin automatically applies the default configuration:
 
 > ```ts
-> // code-pushup.config.ts
-> import { DEFAULT_FLAGS } from 'chrome-launcher/dist/flags.js';
-> ...
-> lighthousePlugin('https://example.com', { output: 'json', chromeFlags: DEFAULT_FLAGS });
+> import lighthousePlugin from '@code-pushup/lighthouse-plugin';
+>
+> lighthousePlugin('https://example.com', {
+>   output: 'json',
+>   // Defaults to DEFAULT_CHROME_FLAGS internally
+> });
+> ```
+
+### Adding Extra Flags
+
+If additional Chrome flags are required (e.g., verbose logging or debugging), they can be appended to the default flags:
+
+> ```ts
+> import lighthousePlugin, { DEFAULT_CHROME_FLAGS } from '@code-pushup/lighthouse-plugin';
+>
+> lighthousePlugin('https://example.com', {
+>   output: 'json',
+>   chromeFlags: DEFAULT_CHROME_FLAGS.concat(['--verbose']),
+> });
+> ```
+
+### Overriding Default Flags
+
+To completely override the default flags and provide a custom configuration:
+
+> ```ts
+> import lighthousePlugin from '@code-pushup/lighthouse-plugin';
+>
+> lighthousePlugin('https://example.com', {
+>   output: 'json',
+>   chromeFlags: ['--verbose'],
+> });
 > ```
 
 ## Config

package/index.js

@@ -1,8 +1,9 @@
 // packages/plugin-lighthouse/package.json
 var name = "@code-pushup/lighthouse-plugin";
-var version = "0.51.0";
+var version = "0.53.0";
 
 // packages/plugin-lighthouse/src/lib/constants.ts
+import { DEFAULT_FLAGS } from "chrome-launcher/dist/flags.js";
 import { join } from "node:path";
 
 // packages/models/src/lib/implementation/schemas.ts
@@ -709,6 +710,7 @@ var reportsDiffSchema = z16.object({
 );
 
 // packages/plugin-lighthouse/src/lib/constants.ts
+var DEFAULT_CHROME_FLAGS = [...DEFAULT_FLAGS, "--headless"];
 var LIGHTHOUSE_PLUGIN_SLUG = "lighthouse";
 var LIGHTHOUSE_OUTPUT_PATH = join(
   DEFAULT_PERSIST_OUTPUT_DIR,
@@ -1052,8 +1054,7 @@ var DEFAULT_CLI_FLAGS = {
   // https://github.com/GoogleChrome/lighthouse/blob/7d80178c37a1b600ea8f092fc0b098029799a659/cli/cli-flags.js#L80
   verbose: false,
   saveAssets: false,
-  // needed to pass CI on linux and windows (locally it works without headless too)
-  chromeFlags: ["--headless=shell"],
+  chromeFlags: DEFAULT_CHROME_FLAGS,
   port: 0,
   hostname: "127.0.0.1",
   view: false,
@@ -1627,6 +1628,7 @@ function lighthousePlugin(url, flags) {
 // packages/plugin-lighthouse/src/index.ts
 var src_default = lighthousePlugin;
 export {
+  DEFAULT_CHROME_FLAGS,
   LIGHTHOUSE_OUTPUT_PATH,
   LIGHTHOUSE_PLUGIN_SLUG,
   LIGHTHOUSE_REPORT_NAME,

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@code-pushup/lighthouse-plugin",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "license": "MIT",
   "description": "Code PushUp plugin for measuring web performance and quality with Lighthouse 🔥",
   "dependencies": {
-    "@code-pushup/models": "0.51.0",
-    "@code-pushup/utils": "0.51.0",
+    "@code-pushup/models": "0.53.0",
+    "@code-pushup/utils": "0.53.0",
     "ansis": "^3.3.0",
+    "chrome-launcher": "^1.1.1",
     "lighthouse": "^12.0.0",
     "lighthouse-logger": "2.0.1"
   },
@@ -19,6 +20,9 @@
     "url": "git+https://github.com/code-pushup/cli.git",
     "directory": "packages/plugin-lighthouse"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "main": "./index.js",
   "types": "./src/index.d.ts"

package/src/index.d.ts

@@ -1,6 +1,6 @@
 import { lighthousePlugin } from './lib/lighthouse-plugin';
 export { LIGHTHOUSE_REPORT_NAME } from './lib/runner';
-export { LIGHTHOUSE_PLUGIN_SLUG, LIGHTHOUSE_OUTPUT_PATH, } from './lib/constants';
+export { DEFAULT_CHROME_FLAGS, LIGHTHOUSE_PLUGIN_SLUG, LIGHTHOUSE_OUTPUT_PATH, } from './lib/constants';
 export { lighthouseAuditRef, lighthouseGroupRef, type LighthouseGroupSlugs, } from './lib/utils';
 export type { LighthouseOptions } from './lib/types';
 export { lighthousePlugin } from './lib/lighthouse-plugin';

package/src/lib/constants.d.ts

@@ -1,2 +1,3 @@
+export declare const DEFAULT_CHROME_FLAGS: string[];
 export declare const LIGHTHOUSE_PLUGIN_SLUG = "lighthouse";
 export declare const LIGHTHOUSE_OUTPUT_PATH: string;