Getting started: Impact Framework

Overview

At its core, CO2.js takes an input of bytes and returns in carbon estimate in grams. In doing so, it provides a way for developers to estimate the carbon cost of data transfer.

In this tutorial, you will use CO2.js within the Impact Framework (IF) to estimate carbon footprint of loading a webpage.

Learning goals

You will learn:

The fundamentals of the Impact Framework
How to install the Impact Framework
How to use CO2.js within the Impact Framework
How to estimate carbon emissions of a webpage of your choosing

Impact Framework Fundamentals

IF is an open source project driven by the Green Software Foundation. It aims to make the environmental impacts of software simpler and more transparent to measure and share. IF works on a command line tool with a plugin ecosystem. These plugins are what makes IF powerful. They provide the functionality for measuring impacts of various software types, and can be written by everyone. There is also a plugin which makes CO2.js usable within IF.

IF plugins are like functions that take a set of input parameters and return a set of output parameters. Plugins can be chained, such that the outputs of one plugin is passed into a subsequent plugin as an input. Such a chain of plugins is called a pipeline. A pipeline is defined in a manifest file, which we will see below.

A manifest file can be run with the IF command line (CLI) tool, if all the necessary plugins are preinstalled.

The CO2.js IF plugin

The CO2.js IF plugin can be used to estimate carbon emissions for a given number of transferred bytes. The plugin offers access to both the Sustainable Web Design (SWD) and the OneByte (1byte) models. If used with the SWD model, it calls the perVisit method to estimate the carbon emissions of the bytes transferred. If additional options are passed, the perVisitTrace method is called instead. With the 1byte model the perByte method is used.

You can check out the Methodologies for calculating website carbon page to learn more about both models, and Methods page for more information on the used methods. For additional information and usage instructions of the plugin, please refer to its readme on GitHub.

Green hosting plugin

The green hosting plugin offers access to CO2.js's hosting check function. It takes a domain and checks whether it is hosted green or not. More details can be found in the plugin's readme on GitHub.

Now that we've established an understanding of Impact Framework and the plugins we'll be using, we will install the Impact Framework and then use it to run a pipeline for estimating the carbon impact of loading a webpage of your choosing.

Prerequisites

You will need to have the following setup on your machine:

Node version 18 or later
NPM version 8 or later

Setting up

First, we install the Impact Framework (IF) globally on our system using NPM. To install the cli tool, run

npm install -g @grnsft/if

To install the plugins necessary for this tutorial, run

npm install -g @tngtech/if-webpage-plugins

This installs the CO2.js plugin, the Webpage Impact plugin and the Green Hosting plugin to measure the data we need.

Manifest file

Now that we are all set up, we can define a manifest file, that uses the CO2.js and the green hosting plugin to define a pipeline for measuring the carbon footprint of loading a webpage.

Let us first look at the pipeline part of the manifest together with its inputs and config options. We are chaining three plugins:

The Webpage Impact plugin (plugin readme)
The Green Hosting plugin (plugin readme)
The CO2.js plugin (plugin readme)

The Webpage Impact plugin essentially takes in a url and measures how many bytes need to be transferred to load the webpage in a browser. It comes with a couple of config options that are described in detail in the GitHub repository.

The plugins are executed in the order defined in the pipeline. The inputs are passed to the first plugin which potentially modifies them or adds additional parameters. The set of updated inputs is then returned. IF takes care of passing them on to the next plugin. This repeats until the last plugin of the pipeline is executed and produces the final output.

Our pipeline

The pipeline we want to build should do the following:

The Webpage Impact plugin is executed first. It takes a URL as an inputs, and returns it along with the number of bytes that were transferred to load the webpage (plus some additional parameters)
These outputs are passed to the Green Hosting plugin, which returns them and adds the result of the green hosting check.
Finally, all values are passed to the CO2.js plugin, which estimates the carbon emissions based on the model specified.

Translating this pipeline in the language of the manifest file, yields the following definition

pipeline:
  observe:
    - webpage-impact
    - green-hosting
  compute:
    - co2js

The first two plugins make observations (gather data). The CO2.js plugin computes the estimated carbon impact with this data.

Measuring the carbon footprint of a webpage

Using this pipeline inside of an IF manifest file will allow us to set up an IF run which loads a web page, scrolls to the bottom, checks for green hosting, and then estimates the carbon emissions of that test using the Sustainable Web Design Model.

First, let's create a folder in which we'll keep our manifest file as well as the output for this project.

mkdir if-measure-webpage-tutorial
cd if-measure-webpage-tutorial

Inside of this folder, create a YAML file which will contain our IF manifest. You can name this whatever you want, but for this tutorial we'll call it manifest.yml.

The manifest file we'll create will need to include additional information on top of the pipeline we specified earlier.

The plugins section specifies the plugins that are used in the pipeline. The tree section contains the information about our pipeline. It can potentially include multiple children and thus multiple pipelines, but we do not need this for our use case.

Plugins can have config options. Please note, that we use them to tell the CO2.js plugin to use the SWD model in version 4. The Webpage Impact plugin is told to load the url www.thegreenwebfoundation.org and scroll the page to the bottom, such that all lazy loaded contents are also loaded and included in the measurement.

The pipeline can take inputs, potentially multiple. We only need one input, that consists of multiple values - that is the options for the SWD model that the CO2.js plugin needs as inputs. We tell the model to assume that 10% of visitors are returning visitors, while 90% are visiting just once.

Our final manifest.yml file looks like this:

name: if-measure-webpage-tutorial
description: example manifest for estimating carbon emissions of a webpage
tags:
initialize:
  outputs:
    - yaml
  plugins:
    'green-hosting':
      method: GreenHosting
      path: '@tngtech/if-webpage-plugins'
    'webpage-impact':
      method: WebpageImpact
      path: '@tngtech/if-webpage-plugins'
      config:
        scrollToBottom: false
        url: https://www.thegreenwebfoundation.org/
    'co2js':
      method: Co2js
      path: '@tngtech/if-webpage-plugins'
      config:
        type: swd
        version: 4
tree:
  children:
    child:
      pipeline:
        observe:
          - webpage-impact
          - green-hosting
        compute:
          - co2js
      inputs:
        - options: # swd model options (co2js plugin)
            firstVisitPercentage: 0.9
            returnVisitPercentage: 0.1

Now, you can run it by executing the following command from inside the if-measure-webpage-tutorial folder we created earlier.

if-run --manifest ./manifest.yml --output ./output.yml

This will create an output file in the root of the current folder. You can change this to a different file path if you wish. Open the output.yml file and check the values reported in the outputs section. The field estimated-carbon holds the estimated carbon impact of loading the specified webpage in grams.

Your inputs and outputs should look similar to the example below.

inputs:
  - options:
      firstVisitPercentage: 0.9
      returnVisitPercentage: 0.1
    timestamp: '2025-01-19T15:10:56.312Z'
    duration: 7.38
    url: https://www.thegreenwebfoundation.org/
    network/data/bytes: 450696
    network/data/resources/bytes:
      Document: 20428
      Stylesheet: 39425
      Script: 63448
      Image: 294447
      Font: 30087
      Other: 2040
      XHR: 821
    green-web-host: true
outputs:
  - options:
      firstVisitPercentage: 0.9
      returnVisitPercentage: 0.1
    timestamp: '2025-01-19T15:10:56.312Z'
    duration: 7.38
    url: https://www.thegreenwebfoundation.org/
    network/data/bytes: 450696
    network/data/resources/bytes:
      Document: 20428
      Stylesheet: 39425
      Script: 63448
      Image: 294447
      Font: 30087
      Other: 2040
      XHR: 821
    green-web-host: true
    estimated-carbon: 0.055 # final result: estimated co2 emissions in grams

We see that, that the two observational plugins added new input values, like network/data/bytes from the Webpage Impact plugin and green-web-host from the Green Hosting plugin. A timestamp was also added.

These inputs are then passed to the CO2.js plugin, which computes the final result estimated-carbon, which is in grams of CO2e emissions.

Prev Getting started: NodeJS

Next Check a domain for green hosting

View the CO2.js changelog

Do you see a bug? Open an issue on GitHub

Do you like CO2.js? Star it on GitHub!

Edit this page on GitHub