seoskills.sh
Catalog/Technical SEO/Puppeteer JS Rendering Auditor

Puppeteer JS Rendering Auditor

Compares each URL's raw HTML with its JavaScript-rendered version in headless Chrome to show the content, links and metadata a crawler would miss.

Listed ·Updated

Built by seoskills.sh

SKILL.md

Puppeteer JS Rendering Auditor

AGENT ROLE: Autonomous rendering-parity agent. For each URL, compare the pre-render and post-render states and emit the JSON in references/output.schema.json. Do not judge SEO quality — only report what content exists before vs after JavaScript.

OBJECTIVE

Detect content, links, and metadata that appear ONLY after JavaScript executes, because a crawler that does not render (or renders on a delay) may never index them.

INPUTS

  • urls (REQUIRED, string[]): absolute URLs to audit.
  • wait_until (OPTIONAL, enum load|domcontentloaded|networkidle0|networkidle2): default networkidle2.
  • render_timeout_ms (OPTIONAL, default 15000).
  • viewport (OPTIONAL, enum mobile|desktop): default mobile (Google indexes mobile-first).
  • block_resources (OPTIONAL bool, default true): block images/fonts/media to speed rendering; NEVER block scripts or XHR.

AUTHENTICATION / RUNTIME

  • No external API key. REQUIRES a headless Chromium.
    • IF puppeteer is installed THEN use its bundled Chromium.
    • ELSE IF env PUPPETEER_EXECUTABLE_PATH is set THEN launch that binary.
    • ELSE STOP error.code="NO_CHROMIUM": "Install puppeteer or set PUPPETEER_EXECUTABLE_PATH to a Chrome/Chromium binary."
  • Chromium's sandbox stays on by default, which is what you want on a normal machine. Only when you are running as root inside a container, where the sandbox cannot start, set the env var PUPPETEER_NO_SANDBOX=1 before running the script; leave it unset everywhere else so the sandbox keeps protecting the host.

EXPECTED TOOL CALLS (per URL)

  1. RAW: fetch(url) (or page.goto with JS disabled) → capture raw_html.
  2. RENDERED: page.goto(url, {waitUntil, timeout}) → page.content() → rendered_html.
  3. Extract from BOTH with the same logic (word count of visible text, a[href] set, <title>, meta description, canonical, robots meta, count of <script type=application/ld+json>).

PROCEDURE (deterministic, per URL)

STEP 1 — Fetch raw HTML. IF non-200 THEN record {url, status, error:"NON_200"} and continue to next URL. STEP 2 — Render with Puppeteer. IF navigation throws/timeouts THEN record render_status="timeout" and use whatever DOM is available. STEP 3 — Compute deltas:

  • text_delta_words = rendered_words - raw_words.
  • links_added = rendered_links − raw_links (set difference); links_removed likewise.
  • meta_changed: object of fields whose value differs (title, description, canonical, robots).
  • jsonld_added = rendered_jsonld_count − raw_jsonld_count. STEP 4 — CLASSIFY severity:
  • high IF text_delta_words > 100 OR links_added.length > 10 OR canonical/robots differ.
  • medium IF any content or ≤10 links added.
  • none IF states are equivalent (good — content is in raw HTML). STEP 5 — EMIT per URL; overall status="ok".

RATE LIMITS & ERROR HANDLING

  • Concurrency: render at most 3 pages in parallel; reuse one browser instance, one page per task, ALWAYS page.close() in a finally block to avoid leaks.
  • Per-URL failure is isolated — never abort the batch for one bad URL.
  • IF the target host returns 429/503 on the raw fetch THEN backoff 2^attempt (max 3) for that URL, then mark error:"RATE_LIMITED".
  • Honor robots.txt: IF a URL is disallowed for the default UA THEN skip with skipped:"robots_disallow" unless respect_robots=false is explicitly passed.

MISSING / INSUFFICIENT DATA

  • IF rendered_html equals raw_html byte-for-byte THEN severity="none", note="no client-side rendering detected".
  • Never infer indexation status; only report the observable render delta.

OUTPUT

One JSON object per references/output.schema.json. No prose.

FILES

  • scripts/render_audit.js — Puppeteer reference implementation (raw vs rendered diff).
  • references/output.schema.json — output contract.

Not using the CLI? Copy the SKILL.md and paste it straight into ChatGPT, Claude, or any agent.

View seoskills-sh/catalog on GitHub

Embed a badge

seoskills.sh listing badge