Skip to content

Commit 04a2702

Browse files
hanna-skrylhanna-skryl
committed
refactor(plugin-lighthouse): rename category aggregation helper
1 parent 40c9b12 commit 04a2702

File tree

5 files changed

+111
-145
lines changed

5 files changed

+111
-145
lines changed

‎code-pushup.preset.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,9 @@ import {
2020
groups,
2121
} from './packages/plugin-jsdocs/src/lib/constants.js';
2222
import {
23+
lighthouseCategories,
2324
lighthouseGroupRef,
2425
lighthousePlugin,
25-
mergeLighthouseCategories,
2626
} from './packages/plugin-lighthouse/src/index.js';
2727
import typescriptPlugin, {
2828
getCategories,
@@ -224,7 +224,7 @@ export async function configureLighthousePlugin(
224224
];
225225
return {
226226
plugins: [lhPlugin],
227-
categories: mergeLighthouseCategories(lhPlugin, lhCategories),
227+
categories: lighthouseCategories(lhPlugin, lhCategories),
228228
};
229229
}
230230

‎packages/plugin-lighthouse/README.md‎

Lines changed: 74 additions & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -51,66 +51,6 @@ For more infos visit the [official docs](https://developer.chrome.com/docs/light
5151

5252
4. Run the CLI with `npx code-pushup collect` and view or upload the report (refer to [CLI docs](../cli/README.md)).
5353

54-
### Optionally set up categories
55-
56-
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).
57-
58-
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).
59-
The plugin exports the helper `lighthouseAuditRef` and `lighthouseGroupRef` to reference Lighthouse category references for audits and groups.
60-
61-
#### Reference audits directly with `lighthouseGroupRef`
62-
63-
```ts
64-
import { lighthouseGroupRef } from './utils';
65-
66-
export default {
67-
// ...
68-
categories: [
69-
{
70-
slug: 'performance',
71-
title: 'Performance',
72-
refs: [lighthouseGroupRef('performance')],
73-
},
74-
{
75-
slug: 'a11y',
76-
title: 'Accessibility',
77-
refs: [lighthouseGroupRef('accessibility')],
78-
},
79-
{
80-
slug: 'best-practices',
81-
title: 'Best Practices',
82-
refs: [lighthouseGroupRef('best-practices')],
83-
},
84-
{
85-
slug: 'seo',
86-
title: 'SEO',
87-
refs: [lighthouseGroupRef('seo')],
88-
},
89-
],
90-
};
91-
```
92-
93-
#### Reference groups with `lighthouseAuditRef`
94-
95-
The Lighthouse categories are reflected as groups.
96-
Referencing individual audits offers more granularity. However, keep maintenance costs of a higher number of audits in mind as well.
97-
98-
```ts
99-
import { lighthouseAuditRef } from './utils';
100-
101-
export default {
102-
// ...
103-
categories: [
104-
{
105-
slug: 'core-web-vitals',
106-
title: 'Core Web Vitals',
107-
scoreTarget: 0.9,
108-
refs: [lighthouseAuditRef('largest-contentful-paint', 3), lighthouseAuditRef('first-input-delay', 2), lighthouseAuditRef('cumulative-layout-shift', 2), lighthouseAuditRef('first-contentful-paint', 1)],
109-
},
110-
],
111-
};
112-
```
113-
11454
## Multiple URLs
11555

11656
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 {
14888
};
14989
```
15090

151-
### Categories with multiple URLs
152-
153-
When running Lighthouse against multiple URLs, use the `mergeLighthouseCategories` utility to ensure categories are correctly expanded and results are aggregated per URL.
154-
155-
#### Basic usage
156-
157-
```ts
158-
import lighthousePlugin, { mergeLighthouseCategories } from '@code-pushup/lighthouse-plugin';
159-
160-
const lhPlugin = await lighthousePlugin(urls);
161-
162-
export default {
163-
plugins: [
164-
// ...
165-
lhPlugin,
166-
],
167-
categories: [
168-
// ...
169-
...mergeLighthouseCategories(lhPlugin),
170-
],
171-
};
172-
```
173-
174-
#### Custom categories
175-
176-
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.
177-
178-
```ts
179-
import lighthousePlugin, { lighthouseAuditRef, lighthouseGroupRef, mergeLighthouseCategories } from '@code-pushup/lighthouse-plugin';
180-
181-
const lhPlugin = await lighthousePlugin(urls);
182-
183-
export default {
184-
// ...
185-
plugins: [
186-
// ...
187-
lhPlugin,
188-
],
189-
categories: [
190-
// ...
191-
...mergeLighthouseCategories(lhPlugin, [
192-
{
193-
slug: 'performance',
194-
title: 'Performance',
195-
refs: [lighthouseGroupRef('performance'), lighthouseAuditRef('first-contentful-paint', 2)],
196-
},
197-
]),
198-
],
199-
};
200-
```
201-
202-
### Behavior Summary
203-
204-
- **No categories**: The plugin auto-generates categories from the plugin's default Lighthouse groups.
205-
- **Custom categories**: The plugin expands all referenced audits and groups for each URL, applying appropriate weights.
206-
- **Empty array** (`categories: []`): No categories are created or expanded, which is useful when you only want audit data.
207-
20891
## Flags
20992

21093
The plugin accepts an optional second argument, `flags`.
@@ -324,4 +207,78 @@ For a complete guide on Lighthouse configuration read the [official documentatio
324207
> })
325208
> ```
326209
210+
## Category integration
211+
212+
The plugin provides helpers to integrate Lighthouse results into your categories.
213+
214+
### Auto-generate categories
215+
216+
Use `lighthouseCategories` to automatically create categories from all plugin groups:
217+
218+
```ts
219+
import lighthousePlugin, { lighthouseCategories } from '@code-pushup/lighthouse-plugin';
220+
221+
const lighthouse = await lighthousePlugin('https://example.com');
222+
223+
export default {
224+
plugins: [lighthouse],
225+
categories: lighthouseCategories(lighthouse),
226+
};
227+
```
228+
229+
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.
230+
231+
### Custom categories
232+
233+
For fine-grained control, provide your own categories. You can reference groups (Lighthouse's native categories) or individual audits:
234+
235+
```ts
236+
import lighthousePlugin, { lighthouseAuditRef, lighthouseCategories, lighthouseGroupRef } from '@code-pushup/lighthouse-plugin';
237+
238+
const lighthouse = await lighthousePlugin(['https://example.com', 'https://example.com/about']);
239+
240+
export default {
241+
plugins: [lighthouse],
242+
categories: lighthouseCategories(lighthouse, [
243+
{
244+
slug: 'performance',
245+
title: 'Performance',
246+
refs: [lighthouseGroupRef('performance')],
247+
},
248+
{
249+
slug: 'core-web-vitals',
250+
title: 'Core Web Vitals',
251+
refs: [lighthouseAuditRef('largest-contentful-paint', 3), lighthouseAuditRef('cumulative-layout-shift', 2), lighthouseAuditRef('first-contentful-paint', 1)],
252+
},
253+
]),
254+
};
255+
```
256+
257+
> [!NOTE]
258+
> 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.
259+
260+
> [!TIP]
261+
> Weights determine each ref's influence on the category score. Use weight `0` to include a ref as info only, without affecting the score.
262+
263+
> [!TIP]
264+
> 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.
265+
266+
### Helper functions
267+
268+
| Function | Description |
269+
| ---------------------- | -------------------------------------------- |
270+
| `lighthouseCategories` | Auto-generates or expands categories |
271+
| `lighthouseGroupRef` | Creates a category ref to a Lighthouse group |
272+
| `lighthouseAuditRef` | Creates a category ref to a Lighthouse audit |
273+
274+
### Type safety
275+
276+
The `LighthouseGroupSlug` type is exported for discovering valid group slugs:
277+
278+
```ts
279+
import type { LighthouseGroupSlug } from '@code-pushup/lighthouse-plugin';
280+
281+
const group: LighthouseGroupSlug = 'performance';
282+
```
283+
327284
If you want to contribute, please refer to [CONTRIBUTING.md](./CONTRIBUTING.md).

‎packages/plugin-lighthouse/src/index.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,7 @@ export { lighthouseAuditRef, lighthouseGroupRef } from './lib/utils.js';
1010
export type { LighthouseGroupSlug, LighthouseOptions } from './lib/types.js';
1111
export { lighthousePlugin } from './lib/lighthouse-plugin.js';
1212
export default lighthousePlugin;
13-
export { mergeLighthouseCategories } from './lib/merge-categories.js';
13+
export {
14+
lighthouseCategories,
15+
mergeLighthouseCategories,
16+
} from './lib/categories.js';

packages/plugin-lighthouse/src/lib/merge-categories.ts renamed to packages/plugin-lighthouse/src/lib/categories.ts

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,10 @@ import { isLighthouseGroupSlug } from './utils.js';
2828
* const lhPlugin = await lighthousePlugin(urls);
2929
* const lhCoreConfig = {
3030
* plugins: [lhPlugin],
31-
* categories: mergeLighthouseCategories(lhPlugin),
31+
* categories: lighthouseCategories(lhPlugin),
3232
* };
3333
*/
34-
export function mergeLighthouseCategories(
34+
export function lighthouseCategories(
3535
plugin: Pick<PluginConfig, 'groups' | 'context'>,
3636
categories?: CategoryConfig[],
3737
): CategoryConfig[] {
@@ -45,6 +45,12 @@ export function mergeLighthouseCategories(
4545
return expandCategories(categories, plugin.context);
4646
}
4747

48+
/**
49+
* @deprecated
50+
* Helper is renamed, please use `lighthouseCategories` function instead.
51+
*/
52+
export const mergeLighthouseCategories = lighthouseCategories;
53+
4854
function createCategories(
4955
groups: Group[],
5056
context: PluginUrlContext,

0 commit comments

Comments
 (0)