EcoTrace

Make sustainability part of your development pipeline.

EcoTrace is a VS Code extension that detects carbon-heavy web patterns in your code, shows CO₂ estimates per page load, and provides quick fixes — directly in your editor. It also ships a standalone CLI for use in CI/CD pipelines.

Features

• Inline diagnostics — squiggles on carbon-heavy patterns (images, videos, scripts, iframes, JS patterns)
• CO₂ estimates — based on actual local file sizes using the Sustainable Web Design model (0.25g CO₂/MB)
• Quick fixes — one-click fixes via the lightbulb menu (Cmd+.)
• Grade system — A through F based on total CO₂ per page load
• Session tracking — shows grade change since you opened the file
• Save notifications — alerts when your grade improves or drops on save
• Carbon report — per-file breakdown with projected daily impact at different traffic levels
• Workspace dashboard — all files ranked by carbon cost
• Ignore comments — suppress specific rules inline
• CLI — run the same analysis outside VS Code, in terminals and CI pipelines

Rules

Grade thresholds

CO₂ methodology

• Transfer-based rules (images, video, scripts, iframes): actual file size is read from disk via fs.statSync. If the file can't be resolved locally (external URL, not found), a fallback average is used.
• Format waste (PNG/JPEG → WebP): waste = fileSize × FORMAT_WASTE_RATIO (PNG saves 70%, JPEG saves 30%)
• Behaviour-based rules (CPU/memory): fixed estimates since they're not data-transfer based
• Model: Sustainable Web Design — 0.25g CO₂ per MB transferred

Fallback sizes used when file can't be resolved:

Ignoring rules

Add an ignore comment on the same line or the line above:

<!-- ecotrace-ignore: missing-lazy-load -->
<img src="https://github.com/carbonscript-xyz/ecotrace/raw/HEAD/hero.png" />

<img src="https://github.com/carbonscript-xyz/ecotrace/raw/HEAD/hero.png" /> <!-- ecotrace-ignore: missing-lazy-load -->

// ecotrace-ignore: console-log
console.log("debug");

Commands

CLI

The same analysis engine is available as a standalone CLI — no VS Code required. Use it in terminals, pre-commit hooks, and CI pipelines.

Usage

node dist/cli.js <files...> [options]

After publishing to npm:

npx ecotrace-cli <files...> [options]

Options

Examples

# Basic scan
node dist/cli.js src/index.html

# Fail CI if any file is below grade C
node dist/cli.js src/**/*.html src/**/*.ts --threshold C

# JSON output (for dashboards or parsing)
node dist/cli.js src/**/*.html --format json | jq '.files[0].grade'

# Only show files with issues
node dist/cli.js src/**/*.html --quiet --threshold B

Exit codes

GitHub Actions

name: EcoTrace
on: [push, pull_request]

jobs:
  eco-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx ecotrace-cli src/**/*.html --threshold C

Local testing (before publishing)

cd ecotrace
pnpm run compile
node dist/cli.js src/index.html --threshold B

Project structure

src/
  analyzer.ts    — pure analysis engine (no VS Code dependency)
                   shared by both the extension and CLI
  extension.ts   — VS Code extension, wraps analyzer with vscode APIs
  cli.ts         — standalone CLI entry point
dist/
  extension.js   — bundled extension (loaded by VS Code)
  cli.js         — bundled CLI (executable, has #!/usr/bin/env node)

Development

pnpm install
pnpm run compile        # type-check + lint + build both extension and CLI
pnpm run watch          # watch mode for extension development
pnpm run check-types    # TypeScript type check only

Press F5 in VS Code to launch an Extension Development Host for testing.

Roadmap

• [ ] CLI published to npm as ecotrace-cli
• [ ] Bundle size analysis (webpack/vite stats integration)
• [ ] Grid carbon intensity — weight CO₂ by deployment region (Electricity Maps API)
• [ ] Third-party script scoring (GTM, HubSpot, Intercom, etc.)
• [ ] Unused CSS detection
• [ ] Historical tracking — CO₂ delta across git commits