PerfLens 🔍

A powerful performance analysis tool for web applications that combines Lighthouse audits with AI-powered code analysis.

This project follows Semantic Versioning. For the versions available, see the tags on this repository.

Features

🌟 Lighthouse Performance Analysis

• Core Web Vitals measurement and scoring
• Performance bottleneck detection
• Resource usage analysis:
  • JavaScript execution and bundle size
  • CSS optimization opportunities
  • Network request analysis
  • Resource loading optimization

🧠 AI-Powered Code Analysis

• Framework-aware code scanning
• Performance pattern detection
• Batch processing of files with:
  • Smart file prioritization
  • Size-based filtering
  • Framework-specific analysis

📊 Rich Reporting

• Detailed HTML reports with:
  • Performance metrics dashboard
  • Critical issues highlighting
  • Code snippets with context
  • Actionable recommendations
• Markdown report generation
• File-specific insights

Installation

Install PerfLens as a dev dependency in your project:

npm install --save-dev perf-lens
# or
yarn add -D perf-lens
# or
pnpm add -D perf-lens

Add scripts to your package.json:

{
  "scripts": {
    "analyze": "perf-lens scan",
    "analyze:html": "perf-lens scan --output reports/performance.html --format html",
    "analyze:md": "perf-lens scan --output reports/performance.md"
  }
}

Now you can run PerfLens using:

npm run analyze

Global Installation

While not recommended, you can also install PerfLens globally:

npm install -g perf-lens
# Then use directly:
perf-lens scan

Quick Start

1. Configure your AI provider:

# Using environment variables
export PERF_LENS_ANTHROPIC_API_KEY=your_key_here

# Or using the CLI
perf-lens config set-key YOUR_API_KEY --provider anthropic

2. Run PerfLens:

perf-lens scan

The tool will automatically:

• Detect your development server
• Run performance audits
• Analyze your codebase
• Generate a detailed report

Configuration

Create a perflens.config.js file in your project root:

/** @type {import('perf-lens').PerflensConfig} */
export default {
  // Performance thresholds
  thresholds: {
    performance: 90,
    fcp: 2000,
    lcp: 2500,
    tbt: 200,
    cls: 0.1,
    speedIndex: 3000,
    tti: 3800,
  },

  // Bundle size thresholds
  bundleThresholds: {
    maxInitialSize: '250kb',
    maxChunkSize: '50kb',
    maxAsyncChunks: 5,
    maxTotalSize: '1mb',
  },

  // Analysis configuration
  analysis: {
    targetDir: 'src',
    maxFiles: 200,
    batchSize: 20,
    maxFileSize: 102400, // 100KB
    batchDelay: 1000,
    include: [
      // File patterns to include
      '**/*.js',
      '**/*.jsx',
      '**/*.ts',
      '**/*.tsx',
      '**/*.vue',
      '**/*.svelte',
      '**/*.astro',
      '**/*.css',
      '**/*.scss',
      '**/*.less',
      '**/*.sass',
      '**/*.html',
    ],
    ignore: [
      // Patterns to ignore (in addition to .perflensignore)
      '**/node_modules/**',
      '**/dist/**',
      '**/build/**',
    ],
  },

  // Lighthouse configuration
  lighthouse: {
    port: 3000,
    mobileEmulation: true,
    throttling: {
      cpu: 4,
      network: 'fast3G',
    },
  },

  // Output configuration
  output: {
    format: 'html',
    directory: './reports',
    filename: 'performance-report',
    includeTimestamp: true,
  },

  // AI configuration
  ai: {
    provider: 'anthropic',
    model: 'claude-3-5-haiku-20241022',
    maxTokens: 8192,
    temperature: 0.2,
  },
};

See Configuration Reference for all options.

CLI Options

perf-lens scan [options]

| Option | Description | Default | | -------------------- | -------------------------- | ----------------- | | -c, --config | Path to config file | - | | -p, --port | Development server port | auto-detect | | -t, --target | Target directory to scan | current directory | | -f, --max-files | Maximum files to analyze | 200 | | -b, --batch-size | Files per batch | 20 | | -s, --max-size | Maximum file size (KB) | 100 | | -d, --batch-delay | Delay between batches (ms) | 1000 | | -o, --output | Report output path | - | | --format | Output format (md/html) | md | | --mobile | Enable mobile emulation | false | | --cpu-throttle | CPU slowdown multiplier | 4 | | --network-throttle | Network throttle type | fast3G |

Documentation

• Getting Started Guide
• Configuration Reference
• API Documentation
• Examples

Requirements

• Node.js >= 18
• Running development server
• AI Provider API Key (OpenAI, Anthropic, or Gemini)

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Dependency Licenses

This project uses several open-source packages that are licensed under various licenses:

• Primary License: MIT
• Notable Dependencies:
  • lighthouse (Apache-2.0)
  • axe-core (MPL-2.0) - via Lighthouse
  • Other dependencies are primarily MIT/Apache-2.0 licensed

Please note that some transitive dependencies may have different licenses. We recommend reviewing the licenses of all dependencies if you plan to use this project in a commercial setting.

Built with ❤️ by Moiz Imran

📧 Email: [email protected]