perf-lens
Version:
AI-powered frontend performance optimizer
257 lines (201 loc) • 6.89 kB
Markdown
# PerfLens 🔍
A powerful performance analysis tool for web applications that combines Lighthouse audits with AI-powered code analysis.
[](https://github.com/moiz-imran/perf-lens/actions/workflows/ci.yml)
[](https://badge.fury.io/js/perf-lens)
[](https://opensource.org/licenses/MIT)
[](https://bundlephobia.com/package/perf-lens)
[](https://libraries.io/npm/perf-lens)
[](https://snyk.io/test/github/moiz-imran/perf-lens)
[](https://www.typescriptlang.org/)
[](https://nodejs.org)
> This project follows [Semantic Versioning](https://semver.org/). For the versions available, see the [tags on this repository](https://github.com/moiz-imran/perf-lens/tags).
## 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:
```bash
npm install --save-dev perf-lens
# or
yarn add -D perf-lens
# or
pnpm add -D perf-lens
```
Add scripts to your `package.json`:
```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:
```bash
npm run analyze
```
### Global Installation
While not recommended, you can also install PerfLens globally:
```bash
npm install -g perf-lens
# Then use directly:
perf-lens scan
```
## Quick Start
1. Configure your AI provider:
```bash
# 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:
```bash
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:
```javascript
/** @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](docs/configuration/README.md) for all options.
## CLI Options
```bash
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](docs/guides/getting-started.md)
- [Configuration Reference](docs/configuration/README.md)
- [API Documentation](docs/api/README.md)
- [Examples](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](CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE](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](https://linkedin.com/in/moiz-imran)
📧 Email: moizwasti@gmail.com