@pierrad/web-carbon-analyzer v1.1.0

Web Carbon Analyzer

A tool to measure the carbon footprint of websites using CO2.js and Playwright. This tool loads websites in a headless browser, tracks all resources loaded, and calculates the carbon emissions associated with each website visit. It also integrates Lighthouse for performance and accessibility audits, providing a comprehensive analysis of web pages.

Features

• Website Carbon Measurement: Calculate the carbon footprint of any website
• Detailed Resource Analysis: Track and analyze all resources loaded by the website
• Green Hosting Detection: Identify whether resources are served from green-powered hosting
• User Behavior Simulation: Simulate realistic user interactions including scrolling
• Comprehensive Results: Get detailed breakdowns by resource type, domain, and more
• Lighthouse Integration: Audit web pages for performance, accessibility, and best practices
• Flexible API: Use as a library in your own projects or as a standalone CLI tool
• Docker Support: Run easily in containerized environments

Installation

As a Library

npm install @pierrad/web-carbon-analyzer

As a CLI Tool

For global installation:

npm install -g @pierrad/web-carbon-analyzer

From Source

1. Clone the repository:

   git clone <repository-url>
   cd web-carbon-analyzer

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Start the application:

   npm run start

Usage

As a Library

// CommonJS
const { CarbonFootprintAnalyzer } = require('web-carbon-analyzer');

// ES Modules
import { CarbonFootprintAnalyzer } from 'web-carbon-analyzer';

async function analyzeWebsite() {
  // Create analyzer with default configuration
  const analyzer = new CarbonFootprintAnalyzer();
  
  // Or with custom configuration
  const customAnalyzer = new CarbonFootprintAnalyzer({
    browser: {
      headless: true,
      timeout: 30000,
      viewport: { width: 1440, height: 900 }
    },
    co2: {
      model: 'swd',
      includeGreenHostingCheck: true
    },
    output: {
      includeResourceDetails: true
    },
    // Lighthouse integration
    lighthouse: {
      enabled: true,
      port: 9222,  // Port for Chrome remote debugging
      thresholds: {
        performance: 70,
        accessibility: 80,
        'best-practices': 80,
        seo: 80
      },
      reports: {
        formats: {
          json: true,
          html: true
        }
      }
    }
  });
  
  try {
    // Analyze a website
    const results = await analyzer.analyze('https://example.com');
    
    // Access results
    console.log(`Total CO2: ${results.summary.totalEmissions}g`);
    console.log(`Total Size: ${results.summary.totalSize} bytes`);
    console.log(`Green Hosting: ${results.summary.percentageGreen}%`);
    
    // Examine detailed breakdowns
    for (const [type, data] of Object.entries(results.breakdowns.byType)) {
      console.log(`${type}: ${data.emissions}g CO2, ${data.size} bytes`);
    }
    
    // Access Lighthouse results if available
    if (results.lighthouse) {
      console.log(`Performance Score: ${results.lighthouse.scores.performance}`);
      console.log(`Accessibility Score: ${results.lighthouse.scores.accessibility}`);
      console.log(`First Contentful Paint: ${results.lighthouse.metrics.firstContentfulPaint}ms`);
      console.log(`Largest Contentful Paint: ${results.lighthouse.metrics.largestContentfulPaint}ms`);
    }
    
    return results;
  } catch (error) {
    console.error('Analysis failed:', error);
    throw error;
  }
}

analyzeWebsite();

As a CLI Tool

# Basic usage
carbon-analyzer --url https://example.com

# Save results to a file
carbon-analyzer --url https://example.com --output results.json

# With detailed resource breakdown
carbon-analyzer --url https://example.com --detailed

# Custom viewport and scrolling
carbon-analyzer --url https://example.com --viewport 1440x900 --scroll-depth 10

# Use a specific CO2 calculation model
carbon-analyzer --url https://example.com --model 1byte

# Run with Lighthouse audit
carbon-analyzer --url https://example.com --lighthouse

# Run with Lighthouse audit and custom performance thresholds
carbon-analyzer --url https://example.com --lighthouse --lighthouse-performance-threshold 80

Docker Usage

# Build the Docker image
docker build -t web-carbon-analyzer .

# Basic usage
docker run web-carbon-analyzer --url https://example.com

# Save results to a mounted volume
docker run -v $(pwd)/results:/data web-carbon-analyzer --url https://example.com --output /data/results.json

# With detailed options
docker run web-carbon-analyzer --url https://example.com --detailed --viewport 1440x900 --scroll-depth 10

Lighthouse Integration

Web Carbon Analyzer can run a Lighthouse audit alongside the carbon footprint analysis, providing performance and accessibility metrics for your website.

Lighthouse Metrics

The following metrics are included in the Lighthouse report:

• Performance Score: Overall performance score (0-100)
• Accessibility Score: Accessibility compliance score (0-100)
• First Contentful Paint: Time until the first content is rendered
• Largest Contentful Paint: Time until the largest content element is rendered
• Total Blocking Time: Sum of all time periods between FCP and TTI
• Speed Index: How quickly the contents of a page are visibly populated
• Time to Interactive: Time it takes for the page to become fully interactive
• Cumulative Layout Shift: Measures visual stability of a page

Enabling Lighthouse

As a Library

const analyzer = new CarbonFootprintAnalyzer({
  lighthouse: {
    enabled: true,
    port: 9222,  // Port for Chrome remote debugging
    thresholds: {
      performance: 70,
      accessibility: 80,
      'best-practices': 80,
      seo: 80
    }
  }
});

As a CLI Tool

carbon-analyzer --url https://example.com --lighthouse

You can also set performance thresholds:

carbon-analyzer --url https://example.com --lighthouse --lighthouse-performance-threshold 80 --lighthouse-accessibility-threshold 90

API Reference

CarbonFootprintAnalyzer

The main class for analyzing websites.

Constructor

new CarbonFootprintAnalyzer(config?: Partial<AppConfig>)

• config: Optional configuration object to customize the analyzer behavior.

Methods

analyze(url: string): Promise<FormattedResults>

Analyzes a website and returns the carbon footprint data.

• url: The URL of the website to analyze.
• Returns: A promise that resolves to the analysis results.

getConfig(): AppConfig

Gets the current configuration.

• Returns: The current configuration object.

updateConfig(newConfig: Partial<AppConfig>): void

Updates the current configuration.

• newConfig: Partial configuration object to merge with the current configuration.

loadCookies(cookiesPath: string): Promise<void>

Loads cookies from a JSON file for authentication or session management.

• cookiesPath: Path to a JSON file containing cookies.

Configuration Options

The AppConfig interface contains the following configuration sections:

browser

Browser and page configuration options.

• type: Browser type ('chromium', 'firefox', or 'webkit') (default: 'chromium')
• headless: Whether to run the browser in headless mode (default: true)
• timeout: Page load timeout in milliseconds (default: 30000)
• networkIdleTimeout: Wait time for network idle in milliseconds (default: 1000)
• waitForNetworkIdle: Whether to wait for network idle (default: true)
• viewport: Browser viewport dimensions (default: { width: 1920, height: 1080 })
• userAgent: Custom user agent string (optional)
• httpCredentials: HTTP authentication credentials (optional)

userBehavior

User behavior simulation options.

• scrollDepth: Number of page heights to scroll (default: 3)
• scrollDelay: Delay between scrolls in milliseconds (default: 500)
• maxScrollTime: Maximum scroll time in milliseconds (default: 10000)

co2

Carbon calculation options.

• model: CO2 calculation model ('swd' or '1byte') (default: 'swd')
• includeGreenHostingCheck: Whether to check for green hosting (default: true)

output

Output format options.

• format: Output format ('json' or 'csv') (default: 'json')
• includeResourceDetails: Whether to include detailed resource breakdown (default: false)
• includeComparisons: Whether to include comparisons (default: true)

lighthouse

Lighthouse integration options.

• enabled: Whether to enable Lighthouse audits (default: false)
• port: Port for Chrome remote debugging (default: 9222)
• thresholds: Performance thresholds for audits
  • performance: Minimum performance score (default: 70)
  • accessibility: Minimum accessibility score (default: 80)
  • best-practices: Minimum best practices score (default: 80)
  • seo: Minimum SEO score (default: 80)
• reports: Report generation options
  • formats: Report formats to generate (default: { json: true, html: true })

Result Structure

The FormattedResults interface contains the following sections:

metadata

Metadata about the analysis.

• url: The URL that was analyzed
• timestamp: When the analysis was performed
• duration: Duration of the analysis in milliseconds
• configuration: Configuration used for the analysis

summary

Summary of the carbon footprint.

• totalEmissions: Total CO2 emissions in grams
• totalSize: Total page size in bytes
• totalRequests: Total number of requests
• percentageGreen: Percentage of resources from green hosting
• comparisons: Comparisons with real-world equivalents

breakdowns

Detailed breakdowns of carbon emissions.

• byType: Emissions broken down by resource type
• byDomain: Emissions broken down by domain
• byHosting: Emissions broken down by hosting type (green/non-green)

resources

(Optional) Detailed information about each resource.

lighthouse

(Optional) Lighthouse audit results.

• scores: Audit scores for performance, accessibility, best practices, and SEO
• metrics: Key performance metrics such as First Contentful Paint and Largest Contentful Paint
• stackPacks: Lighthouse stack packs for detailed analysis

Command Line Options

Example Usage Patterns

Multiple Website Analysis

You can find example usage patterns in the examples directory, including:

• Basic usage example
• Multiple website analysis in parallel
• Web app example

License

MIT