Keep up with web platform changes without a reading list
You can keep up with new web platform guidance by checking your code against it every night and filing a ticket for each rule it breaks. The ticket names the file and line, and quotes the rule.
I had a folder of articles I meant to read on weekends (I never did). Now an agent writes the checks once, and a nightly script files the tickets.
Where the guidance comes from
You need a source that’s current and written for agents as well as people. The Chrome team publishes one as an npm package, modern-web-guidance (1.0.1 when I wrote this, docs here). It’s a CLI:
npx modern-web-guidance list # 209 use cases, one JSON object each
npx modern-web-guidance retrieve security # one guide, as Markdown
The guides are written as rules, with DO and DO NOT lines. The security guide says this about violation reports:
DO NOT: Include sensitive data (PII, authentication tokens, session identifiers, query strings with secrets) in logs or violation reports.
It also ships legacy-scan, which looks for old patterns in a codebase. I ran it on a small made-up app (an Express server and a few DOM scripts) that breaks three of the rules:
Modern Web Guidance Analyzer — demo
0 findings from 38 qualified guides.
Note: legacy-scan covers legacy patterns for 38 guides (~20% of the guidance corpus).
Nothing, on code I’d broken on purpose. The scan only covers about a fifth of the guides, mostly CSS and forms, and the security and UI rules my demo breaks are outside it. So for the rest you write your own checks, or have an agent write them.
Step 1: an agent audits once and writes a backlog
Give an agent the guide list and your repo, one time. It only writes a list, and it doesn’t touch the code. This is the prompt:
Run `npx modern-web-guidance list`. For each use case that applies to this
codebase, retrieve the guide and find places the code breaks one of its
rules. For every gap, add an item to backlog.json:
- id: WG-<n>
- guide: the guide id
- gap: one line on what the code does today
- rule: the guide's own sentence it breaks, quoted exactly
- check: a shell command that prints the offending lines today and prints
nothing once the gap is fixed (git grep, or a short node script)
Run each check before adding it, and keep only checks that print a line.
Do not edit application code.
Here’s one item from the demo’s backlog:
{
"id": "WG-2",
"guide": "security",
"gap": "The CSP report handler logs the whole report, page URL and query string included",
"rule": "DO NOT: Include sensitive data (PII, authentication tokens, session identifiers, query strings with secrets) in logs or violation reports.",
"check": "git grep -n -A3 'csp-report' -- src | grep -E 'console\\.log|logger\\.'"
}
A CSP violation report carries the URL of the page it came from (document-uri), query string included. If a password-reset or sign-in link puts a token in the URL, the report endpoint writes that token into your logs.
The other two items: CSP reports go to the old report-uri with no Reporting-Endpoints header, and error toasts delete themselves after 4 seconds, so a person who looked away never sees the error.
Step 2: review the backlog in a pull request
Don’t merge the agent’s list as it comes. Open it as a PR and read every item. Delete what doesn’t apply to you (install-prompt rules in an app that isn’t installable, say). Tighten a check that matches too much.
I learned more from this review than from the articles I saved, because each rule sits next to a line I wrote and I have to decide if it matters here.
Make sure every check prints something now and goes quiet once the gap is fixed. If it can’t go quiet, its ticket can never be closed by the fix, so fix the check before you merge it.
Step 3: a nightly job files three tickets at most
// Usage: node nightly.js backlog.json filed.json
// Runs every backlog check and writes a ticket for the first 3 that still find the gap.
const fs = require('node:fs');
const { execSync } = require('node:child_process');
const MAX_TICKETS = 3;
const backlog = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
const filed = new Set(fs.existsSync(process.argv[3]) ? JSON.parse(fs.readFileSync(process.argv[3], 'utf8')) : []);
function check(cmd) {
try {
return execSync(cmd, { encoding: 'utf8', shell: '/bin/bash' }).trim();
} catch (e) {
if (e.status === 1) return ''; // grep found nothing: the gap is gone
throw new Error(`check broken: ${cmd}`);
}
}
const tickets = [];
for (const item of backlog) {
if (filed.has(item.id) || tickets.length === MAX_TICKETS) continue;
const where = check(item.check);
if (where) tickets.push({ ...item, where });
}
for (const t of tickets) {
fs.writeFileSync(`ticket-${t.id}.md`, [
`# [web-guidance] ${t.gap}`,
`Backlog: ${t.id}`,
'## Where', '```\n' + t.where + '\n```',
`## Guide: ${t.guide}`, `> ${t.rule}`,
`Full text: \`npx modern-web-guidance retrieve ${t.guide}\``,
].join('\n\n') + '\n');
console.log(`${t.id} ${t.gap}\n ${t.where.split('\n').join('\n ')}`);
}
On the demo it prints:
WG-1 CSP reports go to report-uri, with no Reporting-Endpoints header
src/server.js:5: res.setHeader('Content-Security-Policy-Report-Only', "script-src 'self'; report-uri /csp-report");
WG-2 The CSP report handler logs the whole report, page URL and query string included
src/server.js-9- console.log('csp violation', JSON.stringify(req.body));
WG-3 Toasts remove themselves on a timer
src/toast.js:6: setTimeout(() => el.remove(), 4000);
And ticket-WG-2.md reads:
# [web-guidance] The CSP report handler logs the whole report, page URL and query string included
Backlog: WG-2
## Where
```
src/server.js-9- console.log('csp violation', JSON.stringify(req.body));
```
## Guide: security
> DO NOT: Include sensitive data (PII, authentication tokens, session identifiers, query strings with secrets) in logs or violation reports.
Full text: `npx modern-web-guidance retrieve security`
Post each file to your tracker (gh issue create --body-file ticket-WG-2.md works for GitHub Issues) and add its id to filed.json, so it never comes back. And if someone fixes a gap before its ticket goes out, the check goes quiet and it’s never filed. I tried that on the demo: swap the toast timer for a close button and the next run prints nothing for WG-3.
I cap it at 3 a night. A pile of platform tickets on one morning is easy to skip; 3 get read. They’re also small enough to paste into a coding agent as they are, and rerunning the check tells you whether its fix worked.
Keep the source fresh
The guides get new releases. Pin a version in your audit prompt so the backlog doesn’t shift under you, and rerun the audit when you bump it. New rules show up as new backlog items in that PR.
Where to start
Start with the security guide; in the demo that’s where the worst gap was. Write 4 or 5 checks for it, by hand or with an agent, and run nightly.js once by hand before you schedule it.