@code-pushup/lighthouse-plugin 0.95.2 → 0.96.1

package/README.md

@@ -51,66 +51,6 @@ For more infos visit the [official docs](https://developer.chrome.com/docs/light
 
 4. Run the CLI with `npx code-pushup collect` and view or upload the report (refer to [CLI docs](../cli/README.md)).
 
-### Optionally set up categories
-
-Reference audits (or groups) which you wish to include in custom categories (use `npx code-pushup print-config --onlyPlugins=lighthouse` to list audits and groups).
-
-Assign weights based on what influence each Lighthouse audit has on the overall category score (assign weight 0 to only include as extra info, without influencing category score).
-The plugin exports the helper `lighthouseAuditRef` and `lighthouseGroupRef` to reference Lighthouse category references for audits and groups.
-
-#### Reference audits directly with `lighthouseGroupRef`
-
-```ts
-import { lighthouseGroupRef } from './utils';
-
-export default {
-  // ...
-  categories: [
-    {
-      slug: 'performance',
-      title: 'Performance',
-      refs: [lighthouseGroupRef('performance')],
-    },
-    {
-      slug: 'a11y',
-      title: 'Accessibility',
-      refs: [lighthouseGroupRef('accessibility')],
-    },
-    {
-      slug: 'best-practices',
-      title: 'Best Practices',
-      refs: [lighthouseGroupRef('best-practices')],
-    },
-    {
-      slug: 'seo',
-      title: 'SEO',
-      refs: [lighthouseGroupRef('seo')],
-    },
-  ],
-};
-```
-
-#### Reference groups with `lighthouseAuditRef`
-
-The Lighthouse categories are reflected as groups.
-Referencing individual audits offers more granularity. However, keep maintenance costs of a higher number of audits in mind as well.
-
-```ts
-import { lighthouseAuditRef } from './utils';
-
-export default {
-  // ...
-  categories: [
-    {
-      slug: 'core-web-vitals',
-      title: 'Core Web Vitals',
-      scoreTarget: 0.9,
-      refs: [lighthouseAuditRef('largest-contentful-paint', 3), lighthouseAuditRef('first-input-delay', 2), lighthouseAuditRef('cumulative-layout-shift', 2), lighthouseAuditRef('first-contentful-paint', 1)],
-    },
-  ],
-};
-```
-
 ## Multiple URLs
 
 The Lighthouse plugin supports running audits against multiple URLs in a single invocation. To do this, provide an array of URLs as the first argument to the plugin:
@@ -148,63 +88,6 @@ export default {
 };
 ```
 
-### Categories with multiple URLs
-
-When running Lighthouse against multiple URLs, use the `mergeLighthouseCategories` utility to ensure categories are correctly expanded and results are aggregated per URL.
-
-#### Basic usage
-
-```ts
-import lighthousePlugin, { mergeLighthouseCategories } from '@code-pushup/lighthouse-plugin';
-
-const lhPlugin = await lighthousePlugin(urls);
-
-export default {
-  plugins: [
-    // ...
-    lhPlugin,
-  ],
-  categories: [
-    // ...
-    ...mergeLighthouseCategories(lhPlugin),
-  ],
-};
-```
-
-#### Custom categories
-
-If you provide custom categories, you can reference both groups and audits as usual. The merging utility will expand each referenced group or audit for every URL, assigning the correct per-URL weight.
-
-```ts
-import lighthousePlugin, { lighthouseAuditRef, lighthouseGroupRef, mergeLighthouseCategories } from '@code-pushup/lighthouse-plugin';
-
-const lhPlugin = await lighthousePlugin(urls);
-
-export default {
-  // ...
-  plugins: [
-    // ...
-    lhPlugin,
-  ],
-  categories: [
-    // ...
-    ...mergeLighthouseCategories(lhPlugin, [
-      {
-        slug: 'performance',
-        title: 'Performance',
-        refs: [lighthouseGroupRef('performance'), lighthouseAuditRef('first-contentful-paint', 2)],
-      },
-    ]),
-  ],
-};
-```
-
-### Behavior Summary
-
-- **No categories**: The plugin auto-generates categories from the plugin's default Lighthouse groups.
-- **Custom categories**: The plugin expands all referenced audits and groups for each URL, applying appropriate weights.
-- **Empty array** (`categories: []`): No categories are created or expanded, which is useful when you only want audit data.
-
 ## Flags
 
 The plugin accepts an optional second argument, `flags`.
@@ -324,4 +207,78 @@ For a complete guide on Lighthouse configuration read the [official documentatio
 > })
 > ```
 
+## Category integration
+
+The plugin provides helpers to integrate Lighthouse results into your categories.
+
+### Auto-generate categories
+
+Use `lighthouseCategories` to automatically create categories from all plugin groups:
+
+```ts
+import lighthousePlugin, { lighthouseCategories } from '@code-pushup/lighthouse-plugin';
+
+const lighthouse = await lighthousePlugin('https://example.com');
+
+export default {
+  plugins: [lighthouse],
+  categories: lighthouseCategories(lighthouse),
+};
+```
+
+The helper creates categories for all four Lighthouse groups: `performance`, `accessibility`, `best-practices`, and `seo`. For multi-URL setups, refs are automatically expanded for each URL with appropriate weights.
+
+### Custom categories
+
+For fine-grained control, provide your own categories. You can reference groups (Lighthouse's native categories) or individual audits:
+
+```ts
+import lighthousePlugin, { lighthouseAuditRef, lighthouseCategories, lighthouseGroupRef } from '@code-pushup/lighthouse-plugin';
+
+const lighthouse = await lighthousePlugin(['https://example.com', 'https://example.com/about']);
+
+export default {
+  plugins: [lighthouse],
+  categories: lighthouseCategories(lighthouse, [
+    {
+      slug: 'performance',
+      title: 'Performance',
+      refs: [lighthouseGroupRef('performance')],
+    },
+    {
+      slug: 'core-web-vitals',
+      title: 'Core Web Vitals',
+      refs: [lighthouseAuditRef('largest-contentful-paint', 3), lighthouseAuditRef('cumulative-layout-shift', 2), lighthouseAuditRef('first-contentful-paint', 1)],
+    },
+  ]),
+};
+```
+
+> [!NOTE]
+> Referencing individual audits offers more granularity but increases maintenance costs. Use `npx code-pushup print-config --onlyPlugins=lighthouse` to list all available audits and groups.
+
+> [!TIP]
+> Weights determine each ref's influence on the category score. Use weight `0` to include a ref as info only, without affecting the score.
+
+> [!TIP]
+> You can use `lighthouseGroupRef` and `lighthouseAuditRef` directly in your categories without the helper. However, wrapping them in `lighthouseCategories` future-proofs your config for multi-URL setups.
+
+### Helper functions
+
+| Function               | Description                                  |
+| ---------------------- | -------------------------------------------- |
+| `lighthouseCategories` | Auto-generates or expands categories         |
+| `lighthouseGroupRef`   | Creates a category ref to a Lighthouse group |
+| `lighthouseAuditRef`   | Creates a category ref to a Lighthouse audit |
+
+### Type safety
+
+The `LighthouseGroupSlug` type is exported for discovering valid group slugs:
+
+```ts
+import type { LighthouseGroupSlug } from '@code-pushup/lighthouse-plugin';
+
+const group: LighthouseGroupSlug = 'performance';
+```
+
 If you want to contribute, please refer to [CONTRIBUTING.md](./CONTRIBUTING.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-pushup/lighthouse-plugin",
-  "version": "0.95.2",
+  "version": "0.96.1",
   "license": "MIT",
   "description": "Code PushUp plugin for measuring web performance and quality with Lighthouse 🔥",
   "homepage": "https://github.com/code-pushup/cli/tree/main/packages/plugin-lighthouse#readme",
@@ -36,8 +36,8 @@
   },
   "type": "module",
   "dependencies": {
-    "@code-pushup/models": "0.95.2",
-    "@code-pushup/utils": "0.95.2",
+    "@code-pushup/models": "0.96.1",
+    "@code-pushup/utils": "0.96.1",
     "ansis": "^3.3.0",
     "chrome-launcher": "^1.1.1",
     "lighthouse": "^12.0.0",

package/src/index.d.ts

@@ -5,4 +5,4 @@ export { lighthouseAuditRef, lighthouseGroupRef } from './lib/utils.js';
 export type { LighthouseGroupSlug, LighthouseOptions } from './lib/types.js';
 export { lighthousePlugin } from './lib/lighthouse-plugin.js';
 export default lighthousePlugin;
-export { mergeLighthouseCategories } from './lib/merge-categories.js';
+export { lighthouseCategories, mergeLighthouseCategories, } from './lib/categories.js';

package/src/index.js

@@ -4,5 +4,5 @@ export { DEFAULT_CHROME_FLAGS, LIGHTHOUSE_PLUGIN_SLUG, LIGHTHOUSE_OUTPUT_PATH, }
 export { lighthouseAuditRef, lighthouseGroupRef } from './lib/utils.js';
 export { lighthousePlugin } from './lib/lighthouse-plugin.js';
 export default lighthousePlugin;
-export { mergeLighthouseCategories } from './lib/merge-categories.js';
+export { lighthouseCategories, mergeLighthouseCategories, } from './lib/categories.js';
 //# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAExE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,eAAe,gBAAgB,CAAC;AAChC,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAExE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,eAAe,gBAAgB,CAAC;AAChC,OAAO,EACL,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC"}

package/src/lib/{merge-categories.d.ts → categories.d.ts}

@@ -17,10 +17,15 @@ import type { LighthouseGroupSlug } from './types.js';
  * const lhPlugin = await lighthousePlugin(urls);
  * const lhCoreConfig = {
  *   plugins: [lhPlugin],
- *   categories: mergeLighthouseCategories(lhPlugin),
+ *   categories: lighthouseCategories(lhPlugin),
  * };
  */
-export declare function mergeLighthouseCategories(plugin: Pick<PluginConfig, 'groups' | 'context'>, categories?: CategoryConfig[]): CategoryConfig[];
+export declare function lighthouseCategories(plugin: Pick<PluginConfig, 'groups' | 'context'>, categories?: CategoryConfig[]): CategoryConfig[];
+/**
+ * @deprecated
+ * Helper is renamed, please use `lighthouseCategories` function instead.
+ */
+export declare const mergeLighthouseCategories: typeof lighthouseCategories;
 /**
  * Creates a category config for a Lighthouse group, expanding it for each URL.
  * Only used when user categories are not provided.

package/src/lib/{merge-categories.js → categories.js}

@@ -18,10 +18,10 @@ import { isLighthouseGroupSlug } from './utils.js';
  * const lhPlugin = await lighthousePlugin(urls);
  * const lhCoreConfig = {
  *   plugins: [lhPlugin],
- *   categories: mergeLighthouseCategories(lhPlugin),
+ *   categories: lighthouseCategories(lhPlugin),
  * };
  */
-export function mergeLighthouseCategories(plugin, categories) {
+export function lighthouseCategories(plugin, categories) {
     if (!plugin.groups || plugin.groups.length === 0) {
         return categories ?? [];
     }
@@ -31,10 +31,12 @@ export function mergeLighthouseCategories(plugin, categories) {
     }
     return expandCategories(categories, plugin.context);
 }
+/**
+ * @deprecated
+ * Helper is renamed, please use `lighthouseCategories` function instead.
+ */
+export const mergeLighthouseCategories = lighthouseCategories;
 function createCategories(groups, context) {
-    if (!shouldExpandForUrls(context.urlCount)) {
-        return [];
-    }
     return extractGroupSlugs(groups).map(slug => createAggregatedCategory(slug, context));
 }
 function expandCategories(categories, context) {
@@ -80,4 +82,4 @@ export function extractGroupSlugs(groups) {
     const slugs = groups.map(({ slug }) => removeIndex(slug));
     return [...new Set(slugs)].filter(isLighthouseGroupSlug);
 }
-//# sourceMappingURL=merge-categories.js.map
+//# sourceMappingURL=categories.js.map

package/src/lib/categories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"categories.js","sourceRoot":"","sources":["../../../src/lib/categories.ts"],"names":[],"mappings":"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"}

package/src/lib/merge-categories.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"merge-categories.js","sourceRoot":"","sources":["../../../src/lib/merge-categories.ts"],"names":[],"mappings":"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"}