Restructure plugins list for clarity and trust#6629
Open
jennifer-shehane wants to merge 31 commits into
Open
Conversation
Rework the plugins list page to help users make trustworthy decisions about the plugins they adopt. Trust & clarity: - Add an on-page badge legend and trust framing that explains that community plugins are not vetted by Cypress, plus guidance on how to evaluate a plugin. - Surface live trust signals on every card: npm package + version, last published date (with a "stale" highlight past 18 months), supported Cypress version, weekly downloads, and GitHub stars. - Auto-detect and flag deprecated plugins (unpublished/moved on npm, npm deprecation, or archived repo) with a red badge and an explanatory notice. - Add client-side search and category/trust-level filters. - Document the review criteria and a freshness/removal policy on the page. Data & tooling: - Add scripts/enrich-plugins.mjs (npm run enrich:plugins) to generate trust metadata into src/data/plugins-generated.json from the npm registry and GitHub, with graceful fallback so a flaky network never corrupts the data. - Rework the taxonomy: fix the "Secret Managment" typo, break up the "Development Tools" and "Custom Commands" catch-alls into focused categories, merge single-item categories (e.g. SMS into Email), sort entries by trust tier, and fix keyword-field typos. - Add an optional `npm` field for entries whose display name differs from the package; document the schema and enrichment workflow in CONTRIBUTING. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Replace the hand-rolled month-name array with the built-in Intl.DateTimeFormat (fixed locale + UTC keeps it deterministic across SSR and client). No date library is warranted for this. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Replace hand-rolled helpers in the enrichment script with well-established libraries: - got (with a pre-configured instance) replaces the manual fetch + AbortController timeout + JSON parsing in fetchJson, and adds automatic retries the previous version lacked. - p-map replaces the hand-rolled promise pool for bounded concurrency. - Drop the scoped-name encoding hack; the registry accepts @scope/name paths. Output of the script is byte-for-byte unchanged. Deliberately kept the small GitHub-URL regex and the direct registry/downloads/GitHub calls rather than pulling in heavier deps (pacote, octokit, parse-github-url) for a maintenance script. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Replace the emoji glyphs in the plugin cards with the same FontAwesome icon set the docs already use (npm, clock, gear, download, star, and a warning triangle for deprecations) for visual consistency. Also remove the self-explanatory "how to weigh a plugin" list and the "use the search box below" line from the page intro. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
- Drop the npm brand icon from the npm package trust signal (keep the linked package@version text). - Add cypress/e2e/plugins_list.cy.ts covering the badge legend, default listing, search filtering, empty state, category filter, trust-level filter with deprecated flagging, per-card trust signals, and safe external links. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
- enrich-plugins: read prior metadata from the generated file's `plugins` key so best-effort merges actually preserve committed fields. - enrich-plugins: only flag a plugin deprecated on a definitive npm 404, not on a transient registry/network failure; recompute the flag from fresh data so it can't persist stale. - enrich-plugins: percent-encode the `/` in scoped package names for the downloads API (e.g. @cypress%2Fgrep) so download counts resolve. - plugins-list: defer the date-based "stale" styling until after mount to avoid an SSR/hydration mismatch near the 18-month threshold. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Remove the "How plugins are reviewed" and "Keeping this list current" sections, keeping only the closing invitation to open a PR or issue for outdated or missing plugins. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Link to the plugin usage guide, Node Events overview, Preprocessors API, and configuration reference. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Drop the three plugins currently auto-flagged as deprecated (cypress-testing-library, cypress-drag-drop, cypress-xray-plugin) and list @testing-library/cypress — the maintained successor to cypress-testing-library — in its place. Regenerate plugins-generated.json (now zero deprecated). Update the e2e spec: assert the Deprecated trust level yields the empty state (deprecated plugins are curated out) and that the testing-library successor is listed while the old package is gone. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
cypress-documentation
 |
||||||||||||||||||||||||||||||||||||||||
| Project |
cypress-documentation
|
| Branch Review |
claude/plugins-list-doc-restructure-3yni0g
|
| Run status |
|
| Run duration | 08m 32s |
| Commit |
|
| Committer | Claude |
| View all properties for this run ↗︎ | |
| Test results | |
|---|---|
 |
0
|
 |
0
|
 |
0
|
 |
0
|
 |
655
|
| View all changes introduced in this branch ↗︎ | |
UI Coverage
43.09%
|
|
|---|---|
|
|
412
|
|
|
7
|
Accessibility
96.85%
|
|
|---|---|
|
|
2 critical
4 serious
4 moderate
1 minor
|
|
|
175
|
Render each keyword as an anchor link (styled as a link, not a button) that sets the search filter to that tag on click, reflected in a shareable `?search=` URL that also seeds the filter on load. Clicking scrolls back to the controls so the applied search is visible. Add an e2e test for clicking a tag to filter, and confirm the URL updates. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Audited names/descriptions/keywords against the live npm registry: - Remove cypress-graphql: its npm name is a security-holding placeholder (0.0.1-security), so it is not installable as a real plugin. - Rename cypress-sql -> @dankieu/cypress-sql: the unscoped cypress-sql has no published version; @dankieu/cypress-sql (v2.1.8) is the real package. Also tidy its description. - Fix typos: "gherkin-syntaxed"/"cypress.io" (Cucumber) and "preproccessor" (cypress-vite). - Trim a leading space and grammar in the cypress-env description. - Drop a duplicate "email" keyword on cypress-mailpit. Regenerate plugins-generated.json accordingly. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Show a clear button inside the search field whenever it has a value; clicking it empties the search, removes the ?search= URL param, restores the full list, and refocuses the input. The native webkit search-cancel button is hidden so the control is consistent across browsers. Adds an e2e test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Lead each description with what distinguishes them: the command-line tool that converts DevTools Recorder exports vs. the Chrome DevTools extension that exports directly from the Recorder panel. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Within each category, sort by trust tier (official → verified → community → deprecated) and then by most recent npm publish date, so fresher plugins surface first within a tier. Entries without a publish date sort last with an alphabetical fallback. Done at render time from the generated metadata so it stays current as enrichment re-runs; the entry order in plugins.json no longer matters. Add an e2e test asserting trust-tier order and document the sort in CONTRIBUTING. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
- Accessibility: add Cypress Accessibility (links to the docs). - Code Coverage & Reporting: add UI Coverage (links to the docs). - New "AI Tools" category with Cypress MCP and the three Cypress AI Toolkit skills (cypress-author, cypress-explain, cypress-docs), all marked official and linking to their docs / repo. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
List the categories (and the category filter dropdown) in alphabetical order at render time. Add an e2e test and note the ordering in CONTRIBUTING. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
- Add a "User Interactions" category (native events, drag-and-drop, mobile gestures, tab) peeled out of the Custom Commands grab-bag. - Rename Databases -> "Databases & Storage" and move the localStorage/IndexedDB command plugins into it. - Rename "Framework Tooling" -> "App Framework Integrations". - Rename "Extending Other Testing Frameworks" -> "BDD & Contract Testing". - Rename "Editor & Developer Tooling" -> "Developer Tooling". - Rename "AI Tools" -> "AI Tooling" for consistency with the other tooling categories. Custom Commands drops from 20 to 13 genuinely-generic helpers; no category is thinner than 2 items and all 115 plugins are preserved. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Address review feedback on scripts/enrich-plugins.mjs: - Pin got to ^14 (Node >=20) so `npm run enrich:plugins` runs on the same Node version as the site build; got 15 required Node 22. - Skip GitHub subpath/monorepo links (…/tree/…, …/blob/…) when fetching repo stats, so monorepo packages no longer report cypress-io/cypress's star count. - Detect npm "security holding" placeholders (0.0.x-security) and flag them deprecated instead of presenting them as maintained. - Rebuild metadata from scratch each run: a fresh manifest recomputes every npm signal (so a stale cypressVersion/version can't linger), a definitive 404 drops prior freshness signals, and prior values are preserved only on a transient failure — including an archived flag when the GitHub call fails. - Fall back to the display name as an npm candidate even when an explicit `npm` value is set, so a wrong/removed `npm` can still resolve. Output of the script is unchanged for the current data. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
The badge legend rendered by the PluginsList component already labels and defines each trust level, so drop the bulleted definitions from the page intro and point readers to that key. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
- Frontmatter: keyword-rich title ("Cypress Plugins: Official & Community
Extensions") and a compelling ~157-char meta description.
- Intro: lead with the value plugins provide (what they add and that they're
versioned npm modules with trust signals) instead of a generic one-liner.
- Replace em dashes with plain punctuation across the page copy, plugin/category
descriptions, and the "stale" tooltip.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
- Filter control now reads "All badges" / "Filter by badge"; drop "trust"/ "trust tier"/"trust signals" wording throughout the component, tests, CONTRIBUTING, and the enrichment script (badge-classification wording becomes "badge", the live npm metadata becomes "signals"). - Intro: "typically published as versioned npm modules" (not every entry is an npm package). - Remove the "Choosing the right plugin" heading and its sentence; the badge legend and caution already cover it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Add accurate discovery tags (frameworks, use cases, synonyms) to 47 plugins that had one or two keywords, so the clickable tag links and search surface them more reliably. No entry is left with fewer than three tags. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Add 10 maintained plugins that declare recent Cypress compatibility and weren't listed: - Official Component Testing dev servers: @cypress/vite-dev-server, @cypress/webpack-dev-server. - Community: cypress-split (CI parallelization), @chromatic-com/cypress (visual), cypress-accessibility-checker (IBM Equal Access), @reportportal/agent-js-cypress (reporter), cypress-each, cypress-data-session, cypress-network-idle, cypress-html-validate. Maintenance fixes: - Point "Cypress Image Snapshot" at the maintained @simonsmith/cypress-image-snapshot. - Resolve "Nx" to the @nx/cypress package for accurate signals. Regenerate plugins-generated.json (125 plugins, all resolve, 0 deprecated). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
cypress-solid tests apps built on the Solid Protocol (solidproject.org), not the SolidJS framework. Drop the misleading "solidjs" tag and add "solidproject". Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit f573392. Configure here.
Remove the hydration-wait comment and the redundant "@cypress/grep exists" assertion (implicit in the count check). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
These two card signals were never populated: the npm downloads and GitHub APIs aren't reachable where enrichment runs, and enrichment isn't part of CI, so the committed data always left them empty. Drop them entirely: - Component: remove the downloads and stars rendering (and the now-unused formatDownloads helper and faDownload/faStar imports). - enrich-plugins: remove the weeklyDownloads fetch; reduce the GitHub call to an archived-repo check (still used to flag deprecation) instead of collecting stars/pushedAt; drop the unused downloads endpoint constant. - Regenerate plugins-generated.json (now only npm/version/lastPublished/ cypressVersion) and update the CONTRIBUTING description. Cards still show the npm package, last published date, and Cypress compatibility. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Cypress Accessibility flagged color-contrast failures on the plugins list view: - npm signal link rendered in the theme link color (4.4:1 on the chip), - the amber "Updated" stale text (2.24:1), - muted result-count / empty-state / tag text (4.28:1). Darken these to clear the 4.5:1 threshold: use emphasis-700 for muted text and the npm link, and give the stale indicator accessible amber values with a dark-mode variant. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
Cypress Cloud flagged "clears the search with the clear button" as flaky: the first attempt could type into the search box before React hydrated, so the keystrokes were dropped and the conditionally-rendered clear button never appeared. Expose a `data-hydrated` flag on the component root (flips to true after mount) and have the test's beforeEach wait for it, so interactions never race hydration. Also tidy a garbled comment in the deprecated-filter test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R61G5uKm2a7UFnjNC97LTj
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures the List of Plugins page so users can quickly judge whether a plugin is trustworthy before adopting it: it adds an on-page badge legend and trust framing, surfaces live health signals (npm version, last-published date, Cypress compatibility, downloads, GitHub stars) on every card, auto-flags deprecated plugins, adds search + category/trust-level filters, and reorganizes the flat 12-category list into 17 focused categories.
Why
The plugins list rendered badges (
official/verified/community) whose meaning was never explained on the page — a reader had no way to tell a Cypress-vetted plugin from an unvetted community one without digging intoCONTRIBUTING.md. There were no freshness or maintenance signals at all, so an abandoned plugin looked identical to a thriving one, and two large catch-all categories ("Development Tools", "Custom Commands") held roughly half the entries. This change makes the trust hierarchy legible and gives users concrete data to decide with. The scope came from a request to restructure the page "for better clarity and to assist users in making trustworthy decisions on the plugins they decide to use." The table of contents was intentionally left untouched pending a separate design pass.The trust signals immediately surfaced three plugins that have moved or are unmaintained (
cypress-testing-library,cypress-drag-drop,cypress-xray-plugin), which are now flagged as deprecated.Closes #
Notes for reviewers
keyword/keyboardsfield typos, and movedcypress-sqlout of Email into a new Databases category.downloadsandstarsare empty in the committed data becauseapi.npmjs.organd the GitHub API are blocked from the environment this was authored in.scripts/enrich-plugins.mjsfetches them best-effort; running it in CI or locally with network (and aGITHUB_TOKENto avoid rate limits) will populate them. Version / last-published / Cypress-compat / deprecation are fully populated now (90 plugins resolved, 75 with a Cypress range).prebuild, so a network hiccup can never break site builds. It writessrc/data/plugins-generated.json, which is committed so the site builds offline. The component merges that generated metadata over the curatedplugins.jsonby plugin name.got(HTTP with timeout + retry) andp-map(concurrency) in the enrichment script. I deliberately did not pull in heavier options (pacote,octokit,parse-github-url) for a maintenance script.npmfield for entries whose display name differs from the package (official monorepo packages, scoped names); documented the schema and enrichment workflow inCONTRIBUTING.md.npm run build→ success) plus browser screenshots of the page, an individual card, and the interactive filters (deprecated filter → 3 results, "accessibility" search → 3).🤖 Generated with Claude Code
Generated by Claude Code
Note
Medium Risk
Large documentation UX and data-model change affecting a high-traffic page; incorrect enrichment or taxonomy could mislead users about plugin maintenance, though builds stay offline-safe via committed generated JSON.
Overview
Overhauls the List of Plugins experience so readers can judge trust and freshness before adopting a package.
PluginsListnow merges curatedplugins.jsonwith committedplugins-generated.json: cards show badge tier (with an on-page legend), npm link/version, last publish date, Cypress peer range, deprecation notices, and clickable keyword tags. Search, category, and badge filters sync to?search=in the URL; categories sort A–Z and plugins within each category sort by badge then recency.Adds
npm run enrich:plugins(scripts/enrich-plugins.mjsusinggot/p-map) to refresh registry/GitHub metadata offline-safe (transient failures preserve prior fields).CONTRIBUTING.mddocuments optionalnpm/badgefields, auto-generated signals, and new sort/deprecation rules.plugins.jsonis reorganized into 17 focused categories (new groupings such as AI tooling, test selection, email/SMS), with catalog fixes (e.g.@testing-library/cypresssuccessor, explicitnpmfor monorepo packages) and removals of stale entries per the PR intent.plugins-list.mdxgets SEO copy, community-plugin caution, and see-also links. Cypress e2e (plugins_list.cy.ts) exercises legend, search, filters, sorting, hydration, and card signals.Reviewed by Cursor Bugbot for commit a633897. Bugbot is set up for automated code reviews on this repo. Configure here.