feat(examples): list official and community examples in examples/examples.json

Merged
KA
19d ago
+1467-15

Adds examples/examples.json, the list e2e.tester.army/examples renders, so anyone can add their own example with a pull request.

  • Registry: the 10 starter apps under examples/, plus 7 official use-case examples in their own tester-army repositories (AI chat, Stripe, PayPal, Paddle, RevenueCat, Clerk, iframes).
  • Official vs community: source is official for examples the e2e team maintains under the tester-army organization, community for everyone else's. The site shows official ones with a seal.
  • Tags: framework, useCase, and platform, each a filter on the site. The tag lists live at the top of the file, so labels stay consistent and a contributor adds a missing tag in the same PR.
  • Licenses: the seven tester-army repos are MIT, each licenseUrl pointing at its LICENSE file.
  • Logos: an example can name a logo in examples/icons/ (framework logos for the starter apps, company logos for Stripe and the others); without one, the site shows the e2e logo.
  • Schema: examples/examples.schema.json gives editors autocomplete.
  • Checks: pnpm check:examples (scripts/check-examples.ts, run in spec) rejects:
    • duplicate slugs, undefined tags, and missing icon files
    • an official entry outside tester-army, or a tester-army/e2e entry that is not a folder under examples/
    • a community entry inside tester-army
    • a folder under examples/ with no entry
  • CI: examples-registry.yml also fetches the README of every entry hosted outside this repo, official or community, on PRs that touch the registry. No ruleset requires it, so a network blip does not block merges.
  • Deploys: site.yml now redeploys e2e.tester.army when examples/examples.json or examples/icons/ changes on main.
  • Docs: a new examples/CONTRIBUTING.md explains how to add an example, what we look for, and the rules for official ones. examples/README.md, the root CONTRIBUTING.md, and the site's "Something missing?" card point to it. AGENTS.md notes that a new example folder needs a registry entry and an init preset.
{
  "slug": "nuxt-auth",
  "title": "e2e with Nuxt and Auth.js",
  "description": "Sign-in and protected pages in a Nuxt app.",
  "source": "community",
  "repository": "https://github.com/your-name/nuxt-auth-e2e",
  "author": { "name": "Your Name", "github": "your-name" },
  "license": "MIT",
  "tags": { "framework": ["nuxt", "vue"], "useCase": ["authentication"], "platform": ["web"] }
}
flowchart LR
  PR[PR edits examples/examples.json] --> S[spec: check:examples]
  PR --> R[examples-registry: README reachable]
  S --> M[merge to main]
  M --> H[site.yml: Vercel deploy hook]
  H --> B[e2e-site prebuild downloads examples.json and icons]

The site side is tester-army/e2e-site#62. Merge this one first: the site's build reads this file from main.

Verified

Ran the app locally: yes

  • pnpm check:examples --online: 17 examples OK, every external README reachable.
  • Built e2e-site against this branch (E2E_DOCS_DIR=../e2e/docs) and ran its examples suite. The site now renders all 17 entries, filters by these tags, and shows these logos. Screenshots are on the site PR.
  • Open questions for the owner:
    • Community pages follow the author's branch: a bare repository URL renders the default branch's README, fetched at request time. Edits an author makes after merge go live without review. Requiring a commit SHA in community repository URLs would close that, at the cost of a PR per README update. Raw HTML in READMEs is already dropped by the site (lib/examples/readme.ts) except <img>.
    • paypal.svg is recolored from PayPal's navy to its brighter brand blue so it reads on the dark site (noted in examples/icons/README.md).