Package Exports

@silverassist/performance-toolkit
@silverassist/performance-toolkit/lighthouse
@silverassist/performance-toolkit/pagespeed
@silverassist/performance-toolkit/types

Readme

@silverassist/performance-toolkit

PageSpeed Insights and Lighthouse CI integration for performance monitoring across SilverAssist projects.

Features

✅ PageSpeed Insights API v5 - Full API integration with CrUX data
✅ Lighthouse CI - Programmatic LHCI with node/psi methods
✅ Core Web Vitals - LCP, FCP, CLS, TBT extraction
✅ LCP Element Detection - Identify the LCP element
✅ Opportunities & Diagnostics - Performance improvement suggestions
✅ Actionable Reports - Framework-aware optimization recommendations
✅ Project Context Detection - Auto-detect Next.js, React, Vue, etc.
✅ CLI Tool - Command-line interface for quick analysis
✅ Copilot Prompts & Skills - Pre-built AI workflows for performance optimization
✅ TypeScript - Full type definitions with subpath exports
✅ Multi-Project - Support for FA, CC, AA, OSA

Installation

npm install @silverassist/performance-toolkit
# or
yarn add @silverassist/performance-toolkit
# or
pnpm add @silverassist/performance-toolkit

Quick Start

PageSpeed Insights API

import { analyzeUrl } from "@silverassist/performance-toolkit";

const result = await analyzeUrl("https://www.example.com", {
  strategy: "mobile",
  apiKey: process.env.PAGESPEED_API_KEY,
});

console.log("Performance Score:", result.scores.performance);
console.log("LCP:", result.metrics.lcp.displayValue);
console.log("CLS:", result.metrics.cls.displayValue);

Lighthouse CI Integration

import { createPSIRunner, getDefaultThresholds } from "@silverassist/performance-toolkit";

// Production URLs - use PSI method (consistent hardware)
const runner = createPSIRunner(
  ["https://www.example.com/care-type"],
  process.env.PAGESPEED_API_KEY
)
  .withAssertions(getDefaultThresholds())
  .withTemporaryStorage();

const exitCode = await runner.run();

Staging/Internal URLs

import { createNodeRunner } from "@silverassist/performance-toolkit";

// Staging URLs - use node method (local Chrome)
const runner = createNodeRunner([
  "https://staging.example.com/care-type",
]).withAssertions({
  performance: 50,
  lcp: 4000,
  fcp: 3000,
});

const exitCode = await runner.run();

CLI Usage

# Basic analysis
perf-check https://www.example.com

# Desktop strategy with verbose output
perf-check https://www.example.com --desktop --verbose

# CI mode (exit code 1 on failures)
perf-check https://www.example.com --ci --output results.json

CLI Options

Option	Alias	Description
`--mobile`	`-m`	Use mobile strategy (default)
`--desktop`	`-d`	Use desktop strategy
`--verbose`	`-v`	Show detailed output including opportunities
`--insights`	`-i`	Show all detailed insights (for AI agents)
`--diagnostics`		Show diagnostics table (PageSpeed format)
`--actionable`	`-a`	Generate actionable report with key opportunities
`--detect-context`		Detect project technology stack
`--json`	`-j`	Output structured JSON (for programmatic use)
`--ci`		CI mode (exit with error on violations)
`--output`	`-o`	Output results to JSON file
`--baseline`	`-b`	Compare against baseline file
`--config`	`-c`	Path to configuration file
`--help`	`-h`	Show help message

AI Agent Usage

The toolkit provides detailed, structured insights that AI agents (like GitHub Copilot) can use to identify performance optimization opportunities and propose specific code changes.

# Get detailed insights in terminal format
perf-check https://www.example.com --insights

# Get machine-readable JSON for programmatic analysis
perf-check https://www.example.com --json > report.json

The --insights flag shows:

LCP Timing Breakdown: TTFB, resource load delay, render delay
Third-Party Impact: Blocking time and transfer size per vendor
Unused JavaScript: Wasted bytes with first-party/third-party attribution
Unused CSS: Stylesheets with coverage analysis
Cache Policy Issues: Resources with poor or missing cache headers
Image Optimization: Format, sizing, and lazy-loading opportunities
Legacy JavaScript: Polyfills that can be removed
Render-Blocking Resources: Scripts/styles delaying first paint
Long Tasks: Main-thread blocking tasks with attribution

Example workflow for AI agents:

# 1. Generate structured report
perf-check https://example.com --json > perf-report.json

# 2. AI agent reads the report and identifies issues
# 3. AI agent proposes code changes based on insights.unusedJavaScript, etc.

GitHub Copilot Prompts

The toolkit includes pre-built prompts for GitHub Copilot that provide structured workflows for performance optimization.

Install prompts:

# Create symlink to prompts (recommended - auto-updates with package)
npx perf-prompts install

# Or copy files instead (if you want to customize)
npx perf-prompts install --copy

# Check installation status
npx perf-prompts status

# Remove prompts
npx perf-prompts uninstall

Available prompts:

Prompt	Description
`analyze-performance`	Full performance analysis with actionable report
`optimize-lcp`	LCP optimization with Next.js streaming-aware patterns
`optimize-bundle`	JavaScript bundle analysis and code splitting
`nextjs-performance`	Next.js App Router specific optimizations
`detect-context`	Detect project technology stack
`performance-audit`	Complete multi-phase audit

Usage in VS Code:

@workspace /performance/analyze-performance https://your-site.com
@workspace /performance/optimize-lcp
@workspace /performance/nextjs-performance

Why symlinks? Symlinks ensure prompts stay up-to-date automatically when you update the package. If you need to customize prompts, use --copy instead.

Agent Skills

Agent Skills are auto-loaded by GitHub Copilot based on context relevance (requires chat.useAgentSkills setting in VS Code).

Skill	Description
`nextjs-performance`	Next.js App Router performance patterns
`web-performance-analysis`	General web performance optimization

Skills are installed automatically with npx perf-prompts install.

API Reference

`analyzeUrl(url, options)`

Analyze a single URL using PageSpeed Insights API.

interface PageSpeedOptions {
  url: string;
  strategy?: "mobile" | "desktop";
  categories?: ("performance" | "accessibility" | "best-practices" | "seo")[];
  apiKey?: string;
  timeout?: number;
}

`PageSpeedClient`

Full client for multiple analyses:

import { PageSpeedClient } from "@silverassist/performance-toolkit";

const client = new PageSpeedClient(process.env.PAGESPEED_API_KEY);

// Analyze both strategies
const { mobile, desktop } = await client.analyzeAll(
  "https://www.example.com"
);

`LighthouseRunner`

Programmatic Lighthouse CI:

import { LighthouseRunner } from "@silverassist/performance-toolkit";

const runner = new LighthouseRunner({
  urls: ["https://example.com"],
  method: "psi", // or "node"
  psiApiKey: process.env.PAGESPEED_API_KEY,
  numberOfRuns: 3,
});

// Add assertions
runner.withAssertions({
  performance: 90,
  lcp: 2500,
  cls: 0.1,
});

// Configure upload
runner.withTemporaryStorage();
// or
runner.withLHCIServer("https://lhci.example.com", "build-token");

// Run
const exitCode = await runner.run();

`getDefaultThresholds(strict?)`

Get recommended thresholds:

import { getDefaultThresholds } from "@silverassist/performance-toolkit";

// Standard thresholds
const standard = getDefaultThresholds();
// { performance: 50, lcp: 4000, fcp: 3000, cls: 0.25, tbt: 600 }

// Strict thresholds
const strict = getDefaultThresholds(true);
// { performance: 90, lcp: 2500, fcp: 1800, cls: 0.1, tbt: 200 }

`detectProjectContext()`

Detect the project's technology stack:

import { detectProjectContext } from "@silverassist/performance-toolkit";

const context = await detectProjectContext();

console.log(context.framework); // { name: "Next.js", version: "14.2.0" }
console.log(context.isSSR);     // true
console.log(context.hasAppDir); // true

`generateActionableReport(result, context?)`

Generate an actionable report with framework-specific recommendations:

import { analyzeUrl, generateActionableReport, detectProjectContext } from "@silverassist/performance-toolkit";

const result = await analyzeUrl("https://example.com");
const context = await detectProjectContext();
const report = generateActionableReport(result, context);

console.log(report.keyOpportunities);  // Top 3 prioritized opportunities
console.log(report.lcpAnalysis);       // LCP breakdown and recommendations
console.log(report.nextSteps);         // Prioritized action items

Performance Result

interface PerformanceResult {
  url: string;
  strategy: "mobile" | "desktop";
  timestamp: string;
  scores: {
    performance: number | null;
    accessibility: number | null;
    bestPractices: number | null;
    seo: number | null;
  };
  metrics: {
    lcp: MetricValue;
    fcp: MetricValue;
    cls: MetricValue;
    tbt: MetricValue;
    si: MetricValue;
    tti: MetricValue;
  };
  lcpElement?: {
    tagName: string;
    selector: string;
    url?: string;
  };
  opportunities: Opportunity[];
  diagnostics: Diagnostic[];
  fieldData?: LoadingExperience;
}

Environment Variables

Variable	Description
`PAGESPEED_API_KEY`	Google PageSpeed Insights API key

Get your API key at: https://developers.google.com/speed/docs/insights/v5/get-started

Local Development

The CLI automatically loads .env.local or .env files from the current directory:

# .env.local
PAGESPEED_API_KEY=your-api-key-here

Then simply run:

perf-check https://www.example.com --insights

CI/CD Integration

GitHub Actions

name: Performance Check

on: [push, pull_request]

jobs:
  performance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run Performance Check
        env:
          PAGESPEED_API_KEY: ${{ secrets.PAGESPEED_API_KEY }}
        run: npx perf-check https://www.example.com --ci

Bitbucket Pipelines

pipelines:
  default:
    - step:
        name: Performance Check
        script:
          - npm ci
          - npx perf-check https://www.example.com --ci
        # Set PAGESPEED_API_KEY in Repository Settings > Pipelines > Environment variables

Core Web Vitals Thresholds

Based on Google's guidelines:

Metric	Good	Needs Improvement	Poor
LCP	< 2.5s	2.5s - 4s	> 4s
FCP	< 1.8s	1.8s - 3s	> 3s
CLS	< 0.1	0.1 - 0.25	> 0.25
TBT	< 200ms	200ms - 600ms	> 600ms

TypeScript

Full TypeScript support with exported types:

import type {
  CoreWebVitals,
  MetricValue,
  PerformanceResult,
  PageSpeedOptions,
  LHCIOptions,
  PerformanceThresholds,
} from "@silverassist/performance-toolkit";

Subpath Exports

Import specific modules for smaller bundle size:

// PageSpeed module only
import { PageSpeedClient, analyzeUrl } from "@silverassist/performance-toolkit/pagespeed";

// Lighthouse module only
import { LighthouseRunner, createPSIRunner } from "@silverassist/performance-toolkit/lighthouse";

// Types only (no runtime code)
import type { PerformanceResult, CoreWebVitals } from "@silverassist/performance-toolkit/types";

Development

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Type check
npm run typecheck

# Lint
npm run lint

License

PolyForm Noncommercial License 1.0.0

Links

Made with ❤️ by Silver Assist