Repository navigation
Multi-URL aware helpers for cross-plugin composition #1179
Description
User story
As a Code PushUp user, I want a single utility to compose a category from multiple plugins.
Scenarios
- Single plugin category: User creates a category from one plugin's groups/audits.
- Multi-plugin category: User combines refs from multiple plugins (e.g., Lighthouse + Axe for accessibility).
- Multi-URL transparency: Refs automatically expand for plugins with multi-URL configs; single-URL plugins work unchanged.
- Mixed plugins: Some plugins have multi-URL, others don't; each expands according to its own context.
Acceptance criteria
- Plugin-specific ref helpers handle multi-URL expansion (
lighthouseGroupRefs,axeGroupRefs, etc.) - Helpers accept optional slug parameter (all groups when omitted, specific group when provided)
- Helpers accept optional weight parameter
- Refs can be combined from multiple plugins in a single category
- Single-URL configs work unchanged (no expansion needed)
- Documentation with examples
- Deprecated old helpers (
lighthouseCategories,axeCategories, singular ref helpers)
Implementation details
// Lighthouse helpers
lighthouseGroupRefs(plugin, groupSlug?, weight?): CategoryRef[]
lighthouseAuditRefs(plugin, auditSlug?, weight?): CategoryRef[]
// Axe helpers
axeGroupRefs(plugin, groupSlug?, weight?): CategoryRef[]
axeAuditRefs(plugin, auditSlug?, weight?): CategoryRef[]
// Utils (internal)
expandCategoryRefs(ref, context): CategoryRef[]Usage examples:
import axePlugin, { axeGroupRefs } from '@code-pushup/axe-plugin';
import lighthousePlugin, { lighthouseGroupRefs } from '@code-pushup/lighthouse-plugin';
const urls = ['https://example.com', 'https://example.com/about'];
const axe = axePlugin(urls);
const lighthouse = await lighthousePlugin(urls);
// Single plugin - all groups
categories: [
{
slug: 'a11y',
title: 'Accessibility',
refs: axeGroupRefs(axe),
},
];
// Single plugin - specific group
categories: [
{
slug: 'performance',
title: 'Performance',
refs: lighthouseGroupRefs(lighthouse, 'performance'),
},
];
// Multi-plugin composition
categories: [
{
slug: 'a11y',
title: 'Accessibility',
refs: [...lighthouseGroupRefs(lighthouse, 'accessibility'), ...axeGroupRefs(axe)],
},
];
// Cherry-picked refs with custom weights
categories: [
{
slug: 'a11y',
title: 'Accessibility',
refs: [...axeGroupRefs(axe, 'aria', 2), ...axeGroupRefs(axe, 'color'), ...lighthouseGroupRefs(lighthouse, 'accessibility')],
},
];
Activity
[-]Generic category composition utility for multi-plugin configurations[/-][+]Multi-URL aware helpers for cross-plugin composition[/+]