code-yeongyu/oh-my-openagent / packages/shared-skills/skills/frontend
frontend
FlaggedBuilds, styles, and polishes anything drawn with HTML, CSS, or SVG: web UI, pages, components, HTML reports rendered to PDF or print, figures, PNG/SVG diagrams, slides, and images for Notion or Slack. Use for any styling, layout, animation, or visual-quality task, or when asked to make something look or feel a certain way.
references/perfection/react-perf-tooling.md
View on GitHub# React Perf Tooling for Lighthouse 100
You are auditing or optimizing a React app for Lighthouse 100. Two tools belong in this workflow alongside Playwright + lighthouse — they catch the React-specific perf issues that Lighthouse counts but doesn't diagnose by component:
| Tool | Surface | What it gives you |
|---|---|---|
| **react-scan** (`react-scan/lite`) | Runtime instrumentation, headless | Per-fiber `commit` events with `changeDescription` — "this component re-rendered because <prop / state / context / parent / hook> changed". Correlates with `long-animation-frame` to attribute LoAF to specific components. |
| **react-doctor** | Static scan, CI-friendly | Deterministic findings across state/effects, perf (memoization, list keys, expensive children), architecture, security, a11y. One-shot `npx react-doctor@latest` produces a JSON report. From the Million.dev team. |
Use both. They are complementary: `react-scan` tells you *what's slow right now*; `react-doctor` tells you *what's structurally wrong*. Both are dev-only and free.
If the project does not yet have react-scan and react-doctor wired into its dev environment, read `../design/react-dev-tooling-skill.md` first and install them — they should be on by default for every React project this skill audits.
## Lighthouse run + react-scan/lite
`playwright-lighthouse` already drives a real Chrome. Inject `react-scan/lite` BEFORE React mounts via `page.addInitScript`. Then drain its `onEvent` stream during the run and assert on render budgets at the end.
```ts
// scripts/audit-with-react-scan.ts
import { chromium } from "playwright";
import { playAudit } from "playwright-lighthouse";
declare global {
interface Window {
__renderEvents: unknown[];
}
}
// Narrow only the fields this gate reads from a react-scan commit event.
function hasUnnecessaryRender(event: unknown): boolean {
if (typeof event !== "object" || event === null || !("tree" in event) || !Array.isArray(event.tree)) return false;
return event.tree.some(
(node: unknown) =>
typeof node === "object" &&
node !== null &&
"changeDescription" in node &&
typeof node.changeDescription === "object" &&
node.changeDescription !== null &&
"kind" in node.changeDescription &&
node.changeDescription.kind === "unnecessary",
);
}
const browser = await chromium.launch({ channel: "chrome" });
const context = await browser.newContext();
// Inject react-scan/lite BEFORE the app boots
await context.addInitScript(() => {
// react-scan is a dev dependency of the project (see ../design/react-dev-tooling-skill.md), so its types resolve
import("react-scan/lite").then(({ instrument }) => {
window.__renderEvents = [];
instrument({
onEvent: (event) => {
if (event.kind === "commit") window.__renderEvents.push(event);
},
recordChangeDescriptions: true,
includeFiberSource: true,
includeFiberIdentity: true,
});
});
});
const page = await context.newPage();
await page.goto("http://localhost:3000/<route>");
await playAudit({
page,
port: 9222,
thresholds: { performance: 100, accessibility: 100, "best-practices": 100, seo: 100 },
reports: { formats: { html: true, json: true }, name: "lighthouse-<route>" },
config: { extends: "lighthouse:default", settings: { formFactor: "mobile" } },
});
// Pull render events and assert on render quality
const events = await page.evaluate(() => window.__renderEvents);
const unnecessary = events.filter(hasUnnecessaryRender);
if (unnecessary.length > 0) {
console.error(`FAIL: ${unnecessary.length} unnecessary renders detected during audit`);
for (const e of unnecessary.slice(0, 10)) console.error(" -", JSON.stringify(e, null, 2));
process.exit(1);
}
await browser.close();
```
This is the canonical integration. Run twice per route (mobile + desktop), same as the base Lighthouse workflow. Both must hit 100/100/100/100 AND zero unnecessary renders.
## react-doctor — static perf gate
Before the Playwright run, fail fast on structural issues. The scan is fast and doesn't need a browser, so put it earlier in the pipeline.
```bash
npx react-doctor@latest --json > .react-doctor-report.json
```
Parse `.react-doctor-report.json` for perf-category findings. Treat any perf finding as a blocker for the same reason you treat a Lighthouse score < 100 as a blocker — these are deterministic issues that *will* show up in Lighthouse eventually under throttling.
Wire it into CI as a separate job (cheap, fast, no browser needed):
```yaml
- name: React Doctor static perf scan
uses: millionco/react-doctor@main
```
Or run inline with a fail filter:
```yaml
- name: React Doctor static perf scan
run: npx react-doctor@latest --json --fail-on perf
```
## When to load which during an audit
Run them in this order, stop at the first failure:
1. **`react-doctor`** — cheapest. Catches missing memoization, broken list keys, unstable callback refs, expensive children that re-render unnecessarily. Fix everything it reports BEFORE running Lighthouse — half the perf score wins live here.
2. **`react-scan` interactive in dev** — load the page in real Chrome with `npx react-scan@latest init` already wired (see the dev-tooling reference). Walk the LCP route, the most-clicked CTA, and any animation-heavy view. The toolbar shows render counts; the overlay highlights unnecessary renders in gray. Fix until clean.
3. **`react-scan/lite` in the Lighthouse run** — once interactive is clean, run the Playwright audit above. This catches anything that only shows under throttling or only on first paint.
4. **Playwright + Lighthouse** — standard run from `README.md` audit workflow. Score 100 + zero unnecessary renders from step 3 = done.
## React-specific perf root causes (extends `README.md` ROOT-CAUSE CHECKLIST)
These are the failures `react-scan` and `react-doctor` surface that base Lighthouse won't directly name:
- **Context value identity churn.** A provider value `useMemo` was forgotten; every consumer re-renders on every render of the provider's parent. → `useMemo` the value, or split contexts so high-churn fields don't sit next to stable ones.
- **Inline object/array/callback props on memoized children.** `<Child config={{ a: 1 }} />` breaks `React.memo` every render. → Hoist, `useMemo`, or `useCallback`.
- **List keys = array index.** Reordering shreds the reconciler. → Use a stable id from the data.
- **Expensive components rendered unconditionally above the fold.** → `lazy()` + `Suspense`, or move below the LCP, or pre-render server-side.
- **Effects that fire on every render.** Missing dependency arrays or unstable deps. → Stabilize deps, or split state, or extract to `useEvent`-style ref.
- **Spreading the entire context value into props.** Couples every consumer to every field. → Destructure only the fields used.
- **Hydration mismatches.** SSR markup doesn't equal client first-render. → react-doctor flags structurally; fix the source of the divergence (Date.now, locale, randomness, browser-only APIs).
`react-doctor` finds these statically. `react-scan` confirms the symptom in the running app. Both must come clean before Lighthouse 100 is meaningful.
## Anti-patterns specific to this workflow
- **Forgetting `page.addInitScript` (using `page.evaluate` instead).** `evaluate` runs AFTER React mounts; you'll miss every initial-render event. Use `addInitScript`.
- **`react-scan` non-lite during a Lighthouse run.** The full UI (toolbar, canvas overlay) adds overhead and skews the score. Use `react-scan/lite` ONLY for measurement; the full version is for interactive dev.
- **Reporting Lighthouse 100 with `react-scan` showing 30+ unnecessary renders per route.** The score is meaningless if the React layer is thrashing — INP and CLS will degrade under real load even if the synthetic run passed. Both gates must clear.
- **Treating `trackUnnecessaryRenders` as free.** It has measurable overhead; in a Lighthouse run it can drag the perf score by 2-3 points. Use it for interactive diagnosis, not for the audit run.
- **Skipping react-doctor because "it's just a linter".** It's not. It detects React-specific defects (missing keys, broken memo, unstable refs, hydration mismatches) that ESLint plugins miss because they require fiber-level reasoning.
## Mantra
> **Lighthouse 100 + react-doctor clean + zero unnecessary renders from react-scan. All three or it is not done.**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |