CLAUDE.md · nucliweb/webperf-snippets

Sections

1. Project overview
2. Technology stack
3. Repository layout
4. Commands
5. Snippets
6. Documentation pages
7. Diagrams and demos
8. Notes

First lines (shown under the repo's MIT license)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project overview

**WebPerf Snippets** is a curated collection of web performance measurement JavaScript snippets for the browser console and Chrome DevTools. The repository is a documentation site (Next.js + Nextra) plus the tooling that packages the same snippets as Agent Skills, a CLI and `llms.txt` files.

The snippet source files in `snippets/` are the single source of truth. Documentation pages, skills, the CLI and `llms-full.txt` are all derived from them.

## Technology stack

- **Site**: Next.js 16 App Router with Nextra 4 (`nextra-theme-docs`) and React 19, deployed on Vercel. Search is Pagefind, built after `next build`
- **Media**: Cloudinary URLs (`res.cloudinary.com/nucliweb`), with no SDK
- **Analytics**: Google Analytics and DebugBear
- **CLI** (`cli/`, npm workspace `webperf-snippets`): Playwright runner for the snippets, tested with Vitest

## Repository layout

```
content/                MDX pages, file-system routing, one _meta.js per directory
app/                    Root layout, the [[...mdxPath]] page that renders the MDX, sitemap and robots
mdx-components.js       MDX components of the theme, with the external link label
  CoreWebVitals/ Loading/ Interaction/ Media/ Resources/ DevTools-Overrides/
  index.mdx, which-snippet.mdx, CLI.mdx, visualizer.mdx
snippets/               The snippet sources (*.js), same categories as content/
  SCHEMA.md             Return-value contract every snippet must follow
  _shared/              Helpers marked with `// @shared`
  _view/                The view of a result (labels, formats, order) for the extension, the CLI and the site
components/             Snippet (code block), Callout, Icon, Demo, SnippetVisualizer, diagrams/
components/diagrams/    Own SVG diagrams (Flow, Sequence, custom), styled with --dg-* tokens
lib/                    remark/rehype plugins: browser support, icons, emoji stripping
styles/globals.css      Global styles, including the --dg-* tokens and .wp-support*
public/demos/           Interactive HTML demos; see public/demos/README.md for the contract
skills/, dist/, .claude/skills/   Generated Agent Skills (do not edit by hand)
public/llms.txt, public/llms-full.txt   Generated
public/<page>.md        Markdown version of each page, generated before the build and not committed (lib/page-markdown.mjs)
cli/                    Playwright CLI, workflows, e2e tests and fixtures
extension/              Chrome DevTools panel that runs the snippets (MV3, loaded unpacked)
.claude-plugin/         Marketplace of Claude Code, with the plugins of plugins/
plugins/webperf/        Claude Code plugin with the MCP server of the CLI (npx -y webperf-snippets@1 mcp)
scripts/                Generators, checks and their tests
workspace/              Local notes, ignored by git
```

## Commands

```bash
npm run dev                  # development server (port 3000)
npm run build                # production build (regenerates llms files first)
npm run lint                 # eslint
npm run generate-skills      # regenerate skills/, dist/, .claude/skills/ from snippets/
npm run generate-skills:check  # CI check: generation leaves no diff
npm run test:skills            # every skill script keeps the result objects of its snippet
node scripts/generate-llms.js  # regenerate public/llms*.txt

npm run check:consistency    # shared helpers must carry the `// @shared` marker
npm run check:emoji          # no emoji left in rendered text where an icon exists
npm run test:demos           # demo contract
npm run test:site            # sitemap routes, _meta reader, built snippets check
npm run check:built-snippets # after `npm run build`: every page shows its snippets as in the source
npm run test:icons           # emoji to icon plugins
npm run test:support         # browser support plugin
npm run test:prompt          # agent prompt of each snippet (lib/snippet-prompt.mjs)
npm run extension:build      # extension/snippets.json, then load extension/ unpacked in chrome://extensions
npm run test:view            # view of the results (snippets/_view/), on the fixtures of every snippet
npm run view:fixtures        # regenerate scripts/fixtures/results/ after changing what a snippet returns
npm run test:extension       # DevTools extension: runner, result rendering, catalog
npm run test:extension:e2e   # every snippet through the real panel, on the seeded page of the CLI tests
npm run eval:prompts         # an agent runs the prompts on local pages, graded from its transcript (eval-prompts.yml: on demand and on PRs that change the prompt)

npm run test:unit --prefix cli
npm run smoke:cli-package     # before a CLI release: the packed CLI installed in an empty folder, npm audit of that tree and its MCP server
npm run test:e2e --prefix cli   # Playwright against local fixtures (cli/tests/fixtures)
```

CI (`.github/workflows/ci.yml`) runs lint, build, all the checks above except `eval:prompts`, `generate-skills:check` and the CLI unit and e2e tests. The pre-commit hook (`.githooks/pre-commit`) runs `check:consistency`, `check:emoji` and `lint`.

## Snippets

- Every snippet is an IIFE that returns a structured object with `script`, `status` (`ok`, `tracking`, `error`, `unsupported`) and the metric data. The contract is in `snippets/SCHEMA.md` and is enforced by `cli/tests/e2e/snippet-contract.test.js`.
- A snippet that needs a `PerformanceObserver` entry type checks `PerformanceObserver.supportedEntryTypes` first and returns `status: "unsupported"` when it is missing.
- Chrome exposes some entry types only through observers (`largest-contentful-paint`, `layout-shift`, `longtask`, `event`, `first-input`), so they are read with a buffered observer, not `getEntriesByType`.
- Helpers duplicated across snippets (`formatBytes`, `getRootDomain`) carry a `// @shared` marker and stay identical.
- After changing a snippet: `npm run generate-skills` and `node scripts/generate-llms.js`, and commit the regenerated files.
- Tests come first and use the e2e harness in `cli/tests/helpers/contract.js` and the fixtures in `cli/tests/fixtures/`.

## Documentation pages

`CONTRIBUTING.md` describes the page template step by step. In short:

1. Create `content/<Category>/<Name>.mdx` (kebab-case or the existing naming of the category) and import the snippet with `import snippet from '../../snippets/<Category>/<Name>.js?raw'`, rendered with `<Snippet code={snippet} />`.
2. Register it in the `_meta.js` of the category (`export default { ... }` with a literal object, which `scripts/read-meta.js` reads).
3. Add the `browserSupport` frontmatter and a `### Browser support` section before "Further reading". The badge and tables are generated from MDN browser-compat-data by `lib/remark-browser-support.js`, and the build fails if a key does not exist or the title is missing. `browserSupport` lists what the snippet needs to run; the optional `browserSupportReported` lists what it only audits.
4. If a page is renamed, add a redirect in `next.config.mjs`.

Emojis in MDX are replaced by icons at render time (rehype plugin); the MDX source keeps the emoji.

Writing rules for pages are in "Writing documentation pages" of `CONTRIBUTING.md`: page template, sentence-case headings, no bold as headers, link format, callouts, timeless language.

## Diagrams and demos

- Diagrams are SVG components in `components/diagrams`, not Mermaid. Use `Flow` or `Sequence`, or a custom component, and the `--dg-*` tokens from `styles/globals.css`.
- Demos are standalone HTML files in `public/demos`, embedded with `<Demo>`. They share a style, an icon block (`.ic`) and a contract documented in `public/demos/README.md`, checked by `npm run test:demos`.

## Notes

- `dev` and `build` run with `--webpack`: the plugins of `lib/` are functions, and Nextra 4 does not load them under Turbopack (its loader cannot resolve plugins given as strings). The `?raw` import of the snippets is a webpack rule in `next.config.mjs`; Next 16 keeps its SWC rule outside `oneOf`, so the rule excludes `snippets/` from every SWC rule, or the code reaches the page rewritten. `npm run check:built-snippets` fails after a build when a page shows different code from the source.
- `package.json` pins `zod` to 4.3.6 for `nextra` and `nextra-theme-docs` only, with nested `overrides`: Nextra 4.6.1 fails in `<Layout>` with 4.4.3 or later (`Invalid input: expected nonoptional`, checked again with 4.6.7). The rest of the tree, such as the MCP SDK of the CLI, gets the latest `zod`, which fixes GHSA-mrhx-c7xc-m3w5; Nextra only validates its own configuration with it, at build time. Review it when Nextra is upgraded.
- `agentRules: false` in `next.config.mjs` stops `next dev` from writing a Next.js block into `CLAUDE.md` and `AGENTS.md`.
- The code block and the demo are components of this repository, and `Callout` wraps the one of the theme (`components/`); their styles use `wp-*` classes and `--wp-*` tokens in `styles/globals.css`, never the utility classes of the theme.
- The dev server does not pick up changes in `lib/`; restart it after editing a plugin.
- Images in MDX are Cloudinary URLs in a plain `<img>` with a `srcSet` of transformations (`content/CLI.mdx`); videos use `components/LazyVideoPlayer.js`, a native `<video>` that loads on click.