Skip to content

Commit a3cb477

Browse files
nucliwebnucliweb
committed
Add consistency checks and CI validation
1 parent d9e114c commit a3cb477

File tree

13 files changed

+437
-5
lines changed

13 files changed

+437
-5
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- main
8+
9+
jobs:
10+
validate:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout repository
15+
uses: actions/checkout@v4
16+
17+
- name: Setup Node.js
18+
uses: actions/setup-node@v4
19+
with:
20+
node-version: '22'
21+
cache: 'npm'
22+
23+
- name: Install dependencies
24+
run: npm ci
25+
26+
- name: Lint
27+
run: npm run lint
28+
29+
- name: Build
30+
run: npm run build
31+
32+
- name: Check consistency
33+
run: npm run check:consistency

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ node_modules
66
.vercel
77
reports
88
workspace
9+
public/sitemap-*.xml

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,22 @@
22

33
A curated collection of JavaScript snippets to measure and debug Web Performance directly in your browser's DevTools console.
44

5+
[![CI](https://github.com/nucliweb/webperf-snippets/actions/workflows/ci.yml/badge.svg)](https://github.com/nucliweb/webperf-snippets/actions/workflows/ci.yml)
6+
[![Release](https://img.shields.io/github/v/release/nucliweb/webperf-snippets)](https://github.com/nucliweb/webperf-snippets/releases)
7+
[![Snippets](https://img.shields.io/badge/snippets-47-0f766e)](https://webperf-snippets.nucliweb.net)
8+
[![License](https://img.shields.io/github/license/nucliweb/webperf-snippets)](./LICENSE)
59
[![Star History](https://img.shields.io/github/stars/nucliweb/webperf-snippets?style=social)](https://star-history.com/#nucliweb/webperf-snippets&Date)
610

711
![WebPerf Snippets](https://github.com/nucliweb/webperf-snippets/assets/1307927/f47f3049-34f5-407c-896a-d26a30ddf344)
812

13+
## Start here
14+
15+
- Measure your first page: start with [LCP](https://webperf-snippets.nucliweb.net/CoreWebVitals/LCP), [CLS](https://webperf-snippets.nucliweb.net/CoreWebVitals/CLS), and [INP](https://webperf-snippets.nucliweb.net/CoreWebVitals/INP).
16+
- Investigate slow loading: continue with [TTFB](https://webperf-snippets.nucliweb.net/Loading/TTFB), [FCP](https://webperf-snippets.nucliweb.net/Loading/FCP), and [render-blocking resources](https://webperf-snippets.nucliweb.net/Loading/Find-render-blocking-resources).
17+
- Debug interaction issues: use [Long Animation Frames](https://webperf-snippets.nucliweb.net/Interaction/Long-Animation-Frames) and [Scroll Performance](https://webperf-snippets.nucliweb.net/Interaction/Scroll-Performance).
18+
- Audit media-heavy pages: open [Image Element Audit](https://webperf-snippets.nucliweb.net/Media/Image-Element-Audit) and [Video Element Audit](https://webperf-snippets.nucliweb.net/Media/Video-Element-Audit).
19+
- Automate the workflow with agents: see [SKILLS.md](./SKILLS.md) and the installation section below.
20+
921
## What you can measure
1022

1123
| Category | What it includes |

‎SKILLS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ These skills transform 47 battle-tested JavaScript snippets into agent capabilit
2222
| ------------------------------------------------------- | ---------- | ------------------------------------------------------------ |
2323
| **[webperf](#webperf)** | Meta-skill | "Audit performance", "check web vitals", "analyze this page" |
2424
| **[webperf-core-web-vitals](#webperf-core-web-vitals)** | 7 | "Debug LCP", "check CLS", "measure INP" |
25-
| **[webperf-loading](#webperf-loading)** | 27 | "Analyze TTFB", "check render-blocking", "audit scripts" |
25+
| **[webperf-loading](#webperf-loading)** | 28 | "Analyze TTFB", "check render-blocking", "audit scripts" |
2626
| **[webperf-interaction](#webperf-interaction)** | 8 | "Debug jank", "long tasks", "animation frames" |
2727
| **[webperf-media](#webperf-media)** | 3 | "Audit images", "optimize video", "lazy loading" |
2828
| **[webperf-resources](#webperf-resources)** | 1 | "Check bandwidth", "network quality" |
@@ -105,7 +105,7 @@ The main entry point that helps identify the right skill for your performance qu
105105
**What it does:**
106106

107107
- Routes to the appropriate specialized skill
108-
- Provides overview of all 46 available snippets
108+
- Provides overview of all 47 available snippets
109109
- Suggests which skill to use based on your question
110110

111111
### webperf-core-web-vitals

‎docs/ARCHITECTURE.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Architecture
2+
3+
This repository has four main content layers:
4+
5+
1. `snippets/`
6+
Source of truth for executable JavaScript snippets. Each category contains the browser-console code that users and agents run.
7+
8+
2. `pages/`
9+
Human-facing MDX documentation published by the Nextra site. Most pages document one snippet or a related set of snippets. Editorial pages can be declared with frontmatter such as `type: guide`.
10+
11+
3. `skills/`
12+
Generated Agent Skills built from `snippets/` and `pages/`. These files are not the authoring source. Regenerate them with `npm run generate-skills`.
13+
14+
4. `dist/`
15+
Generated readable artifacts for external consumption. These are also derived outputs, not source files.
16+
17+
## Build Flow
18+
19+
The normal flow is:
20+
21+
`snippets/` + `pages/` -> `scripts/generate-skills.js` -> `skills/` + `dist/`
22+
23+
Supporting files:
24+
25+
- `lib/snippets-registry.js` powers site-level snippet metadata and imports.
26+
- `pages/**/_meta.json` defines sidebar navigation for each section.
27+
- `scripts/check-consistency.js` validates source-to-doc parity, editorial page declarations, `_meta.json` alignment, and published counts.
28+
29+
## Source of Truth
30+
31+
Treat these as editable source:
32+
33+
- `snippets/`
34+
- `pages/`
35+
- `pages/**/_meta.json`
36+
- `lib/snippets-registry.js`
37+
- `README.md`
38+
- `SKILLS.md`
39+
40+
Treat these as generated or derivative:
41+
42+
- `skills/`
43+
- `dist/`
44+
45+
## Common Contributor Workflow
46+
47+
1. Edit or add a snippet in `snippets/`.
48+
2. Add or update its documentation in `pages/`.
49+
3. Update the relevant `_meta.json`.
50+
4. Run `npm run generate-skills` when you intentionally want to refresh derived artifacts.
51+
5. Run `npm run check:consistency`.
52+
6. Run `npm run lint` and `npm run build`.
53+
54+
## When To Regenerate Skills
55+
56+
Run `npm run generate-skills` whenever you change:
57+
58+
- Any file in `snippets/`
59+
- Any MDX page used to build skill descriptions or thresholds
60+
- `package.json` version or metadata that should propagate to generated skills
61+
62+
## Release Relationship
63+
64+
Release packaging reads from generated `skills/`, so stale generated files can leak into release artifacts. Before a release, verify generation explicitly with:
65+
66+
- `npm run check:consistency`
67+
- `npm run generate-skills:check`

‎docs/RELEASING.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Releasing
2+
3+
## Pre-release Checklist
4+
5+
1. Update the version in [package.json](/Users/joanleon/projects/nucliweb/GitHub/webperf-snippets/package.json).
6+
2. Regenerate derived artifacts with `npm run generate-skills`.
7+
3. Verify the generated version in [skills/webperf/SKILL.md](/Users/joanleon/projects/nucliweb/GitHub/webperf-snippets/skills/webperf/SKILL.md).
8+
4. Run:
9+
10+
```bash
11+
npm run lint
12+
npm run build
13+
npm run check:consistency
14+
npm run generate-skills:check
15+
```
16+
17+
5. Commit the source changes together with regenerated `skills/` and `dist/`.
18+
19+
## Tag Release
20+
21+
The release workflow is triggered by pushing a tag that matches `v*`.
22+
23+
Example:
24+
25+
```bash
26+
git tag v1.2.1
27+
git push origin v1.2.1
28+
```
29+
30+
## What The Workflow Produces
31+
32+
The release workflow:
33+
34+
1. Installs dependencies with `npm ci`
35+
2. Regenerates `skills/`
36+
3. Packages each generated skill as a zip
37+
4. Publishes a GitHub Release with:
38+
39+
- `webperf-skills-all.zip`
40+
- `webperf.zip`
41+
- `webperf-core-web-vitals.zip`
42+
- `webperf-loading.zip`
43+
- `webperf-interaction.zip`
44+
- `webperf-media.zip`
45+
- `webperf-resources.zip`
46+
47+
## Failure Modes To Watch
48+
49+
- `skills/webperf/SKILL.md` version does not match `package.json`
50+
- `skills/` or `dist/` are stale relative to `snippets/` or `pages/`
51+
- `_meta.json` entries drift from the actual MDX files
52+
- Published snippet counts in `README.md`, `SKILLS.md`, or `skills/webperf/SKILL.md` are outdated

‎next.config.js‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,6 @@ module.exports = withNextra({
5757
},
5858
];
5959
},
60-
search: {
61-
codeblocks: false,
62-
},
6360
});
6461

6562
// If you have other Next.js configurations, you can pass them as the parameter:

‎package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,9 @@
88
"build": "next build",
99
"postbuild": "next-sitemap",
1010
"prebuild": "rm -rf .next",
11+
"check:consistency": "node scripts/check-consistency.js",
1112
"generate-skills": "node scripts/generate-skills.js",
13+
"generate-skills:check": "node scripts/generate-skills.js && git diff --exit-code -- skills dist",
1214
"install-skills": "node scripts/install-skills.js",
1315
"install-global": "node scripts/install-global.js",
1416
"install-from-release": "node scripts/install-from-release.js",

‎pages/CoreWebVitals/CLS.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,13 @@ stateDiagram-v2
8383
| Dynamic content injection | Reserve space or insert below fold |
8484
| Web fonts (FOIT/FOUT) | Use `font-display: optional` or `size-adjust` |
8585

86+
### Browser Support
87+
88+
| API | Chrome | Firefox | Safari | Edge |
89+
|-----|--------|---------|--------|------|
90+
| Layout Instability API | ✅ 77 | ❌ | ❌ | ✅ 79 |
91+
| PerformanceObserver | ✅ 52 | ✅ 57 | ✅ 11 | ✅ 79 |
92+
8693
### Further Reading
8794

8895
- [Cumulative Layout Shift (CLS)](https://web.dev/articles/cls) | web.dev

‎pages/CoreWebVitals/LCP.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,13 @@ Quick check for [Largest Contentful Paint](https://web.dev/articles/lcp), a Core
4242
| Slow resource load | Preload LCP image, optimize size |
4343
| Client-side rendering | Use SSR or prerender |
4444

45+
### Browser Support
46+
47+
| API | Chrome | Firefox | Safari | Edge |
48+
|-----|--------|---------|--------|------|
49+
| Largest Contentful Paint API | ✅ 77 | ❌ | ❌ | ✅ 79 |
50+
| PerformanceObserver | ✅ 52 | ✅ 57 | ✅ 11 | ✅ 79 |
51+
4552
### Further Reading
4653

4754
- [Largest Contentful Paint (LCP)](https://web.dev/articles/lcp) | web.dev

0 commit comments

Comments
 (0)