Perf-lens NPM | npm.io

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

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

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

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: moizwasti@gmail.com