@inforob/pagespeed-toolkit

An npm-installable toolkit + Claude Code integration for achieving 90–100 PageSpeed scores in JavaScript projects.

Supports Astro, Next.js (App Router & Pages Router), Nuxt 3, Vue+Vite, and React+Vite.

It combines a CLI audit command that calls the Google PageSpeed Insights API, an AI agent that analyzes your project and recommends optimizations, and a slash command that reads audit reports and applies fixes interactively — all wired up automatically on npm install.

Installation

npm install --save-dev @inforob/pagespeed-toolkit
# or
pnpm add -D @inforob/pagespeed-toolkit
# or
yarn add -D @inforob/pagespeed-toolkit

That's it. The postinstall hook automatically:

• Copies .claude/commands/pagespeed-fix.md and .claude/agents/pagespeed-optimizer.md into your project
• Adds "pagespeed:audit": "pagespeed-audit" to your package.json scripts
• Appends PAGESPEED_API_KEY and SITE_URL placeholders to .env.example

The only manual step: fill in your API key in .env.local:

PAGESPEED_API_KEY=your_google_api_key_here
SITE_URL=https://your-site.com

How it works

┌─────────────────────────────────────────────────────────────────┐
│  1. AUDIT                                                       │
│  npm run pagespeed:audit  →  generates pagespeed-report.json    │
│  Audits mobile + desktop for every URL you configure            │
├─────────────────────────────────────────────────────────────────┤
│  2. FIX  (Claude Code)                                          │
│  /pagespeed-fix → Claude reads the report, shows failing        │
│  audits, and applies fixes one by one with your confirmation    │
├─────────────────────────────────────────────────────────────────┤
│  3. REVIEW  (Claude Code)                                       │
│  pagespeed-optimizer agent → deep analysis of your stack,       │
│  deployment config, Core Web Vitals, and framework-specific     │
│  optimizations with copy-paste-ready fixes                      │
└─────────────────────────────────────────────────────────────────┘

Get a Google PageSpeed API key

1. Go to Google Cloud Console
2. Enable the PageSpeed Insights API
3. Create an API key
4. Add it to .env.local: PAGESPEED_API_KEY=your_key_here

The free tier allows ~25,000 requests/day — more than enough for local development.

CLI usage

# Basic — audits SITE_URL on both mobile and desktop
npm run pagespeed:audit

# Specific pages
pagespeed-audit --urls /,/blog,/about

# Mobile only
pagespeed-audit --strategy mobile

# Custom output path
pagespeed-audit --output reports/pagespeed.json

# CI mode — exit 1 if any score falls below threshold
pagespeed-audit --threshold-performance 90 --threshold-seo 90

# Config file
pagespeed-audit --config pagespeed.config.mjs

All options

| Flag | Default | Description | |---|---|---| | --urls | / | Comma-separated paths to audit | | --strategy | both | mobile | desktop | both | | --output | pagespeed-report.json | Output file path | | --threshold-performance | 0 | Min score for CI (0 = disabled) | | --threshold-seo | 0 | Min score for CI | | --threshold-accessibility | 0 | Min score for CI | | --threshold-best-practices | 0 | Min score for CI | | --config | auto | Path to pagespeed.config.mjs | | --version | | Print version | | --help | | Show help |

Environment variables

| Variable | Description | |---|---| | PAGESPEED_API_KEY | Google PageSpeed Insights API key (required) | | SITE_URL | Base URL of the site (required) | | PAGESPEED_STRATEGY | mobile | desktop | both | | PAGESPEED_OUTPUT | Output file path |

Config file

Copy pagespeed.config.example.mjs to pagespeed.config.mjs in your project root:

// pagespeed.config.mjs
export default {
  urls: ['/', '/blog', '/about'],
  strategy: 'both',
  output: 'pagespeed-report.json',
  thresholds: {
    performance: 90,
    seo: 90,
    accessibility: 90,
    'best-practices': 90,
  },
}

Priority order: defaults → config file → env vars → CLI flags.

Claude Code integration

/pagespeed-fix — Interactive fixer

Open Claude Code in your project and run:

/pagespeed-fix

Claude will:

1. Detect your framework automatically (Astro, Next.js, Nuxt, Vue, React)
2. Locate or generate the audit report
3. Show failing audits grouped by category and impact
4. Ask which ones you want to fix
5. Apply each fix with minimum-necessary changes, reading the file first
6. Show a summary of changes and manual action items

pagespeed-optimizer agent — Deep analysis

Ask Claude to launch the optimizer agent:

"Can you check if my project is optimized for PageSpeed?"

The agent will:

• Detect your stack and deployment target (Vercel, Netlify, Nginx/VPS, Cloudflare)
• Audit frontend assets and Core Web Vitals
• Deliver copy-paste-ready fixes per framework with before/after score estimates

Supported frameworks

| Framework | Detection | Fix coverage | |---|---|---| | Astro | astro in package.json | Full (astro:assets, layouts, astro.config.mjs) | | Next.js App Router | next + app/ directory | Full (next/image, next/font, metadata API, next/script) | | Next.js Pages Router | next + pages/ directory | Full (next/image, next/head, _document.tsx) | | Nuxt 3 | nuxt in package.json | Full (<NuxtImg>, useSeoMeta, nuxt.config.ts) | | Vue + Vite | vue + vite | Full (vite.config.ts, SFCs, index.html) | | React + Vite | react + vite | Full (vite.config.ts, JSX/TSX components) |

Programmatic API

import { auditUrl, getCategoryScores, getFailingAudits, runAudit } from '@inforob/pagespeed-toolkit'

// Single URL audit
const data = await auditUrl('https://example.com', 'mobile', process.env.PAGESPEED_API_KEY)
const scores = getCategoryScores(data)   // { performance: 72, seo: 94, ... }
const failing = getFailingAudits(data)   // sorted by score ascending

// Full multi-page audit (generates JSON report)
await runAudit({
  urls: ['/', '/blog'],
  strategy: 'both',
  siteUrl: 'https://example.com',
  apiKey: process.env.PAGESPEED_API_KEY,
  outputPath: 'pagespeed-report.json',
})

CI/CD example (GitHub Actions)

- name: PageSpeed audit
  run: npm run pagespeed:audit -- --threshold-performance 90 --threshold-seo 90
  env:
    PAGESPEED_API_KEY: ${{ secrets.PAGESPEED_API_KEY }}
    SITE_URL: https://your-site.com

Exit code 1 if any score falls below the configured threshold.

Contributing

Contributions are welcome. The most valuable additions are:

1. New framework integrations — extend the fix guide in .claude/commands/pagespeed-fix.md
2. Agent improvements — refine the optimizer agent's detection or output format
3. Deployment targets — add configs for new platforms in the agent

License

MIT