Skip to content

Release Guide: CO2.js v0.14

New release v0.14.1

CO2.js v0.14.1 is the first version release since type definitions for CO2.js became available on NPM through the DefinitelyTyped project. This enables those using CO2.js in TypeScript projects to import definitions.

Type definitions for CO2.js

One of the most active issues in the CO2.js repository over the past couple of years has been to “Introduce just enough typescript“. The aim of this issue was to introduce type definitions into the CO2.js library. This enables those using CO2.js in TypeScript projects to benefit from type checking in their codebase, resulting in a smoother developer experience and greater confidence when using the library.

In the end, we have opted to make type definitions available through the DefinitelyTyped project. This project allows the community to contribute type definitions for a JavaScript library, without requiring code changes to the library itself.

This work was made possible thanks to funding from SIDN Fonds. If you or your organisation would like to fund future work on CO2.js, please consider donating.

Adding CO2.js type definitions to a project

Type definitions for CO2.js are published in the DefinitelyTyped project, and are available on NPM at @types/tgwf__co2.

If you want to use type definitions in your project, they should be installed as a devDependency.

npm install --dev @types/tgwf__co2

Reduced package size

Version 0.14.1 also saw the installed package size of the CO2.js library shrink significantly. Prior to this version, the package size of the library was 476 kB. After reviewing the published contents of the package, we have been able to reduce this to 194 kB.

This change helps those who use CO2.js but are unable to reduce the size code shipped with their projects through strategies such as tree shaking.

A full list of the files the changes made can be found in the CO2.js GitHub repository.

Add User-Agent Headers to Green Checks

Version 0.14.2 of CO2.js introduced User-Agent headers which are now sent along with all green domain checks performed against the Green Web Dataset through CO2.js.

This change helps give us visibility of who is using CO2.js to perform checks against the Green Web Dataset, and what version of the library is being used for this purpose.

The CO2.js version number will be sent as a User-Agent header with every request. Developers can optionally also set the name of their app, website, or project as an extra parameter. We strongly encourage users of CO2.js to do this as it gives us extra visibility of how our free tools are being used.

import { hosting } from "@tgwf/co2";

hosting.check("", "myGreenWebApp")

Updated Average Annual Grid intensity data

In version 0.14.3 of CO2.js (February 2024), we include update annual average grid intensity data from Ember Climate which reflects their updated carbon intensity methodology. The new methodology takes a country-by-country, fuel-by-fuel approach which aims to provide greater accuracy.

Previously, Ember relied on data supplied by the IPCC. Their new methodology sources data from a wider number of data sources, with the aim to providing greater transparency and detail especially around coal and gas generation.

As a result of this change, you will see higher grid intensity values for most countries and regions.

Read the methodology at:

⚠️ Upcoming feature deprecation notice

In the next version of CO2.js (0.15.0) we will be removing some functions that were specific to using CO2.js with Sitespeed’s Page X-ray. Namely, we will be removing the following functions from the CO2.js library:

  • perDomain
  • perPage
  • perContentType
  • dirtiestResources
  • perParty`

This functionality has already been merged into the Sustainability Plugin. Once the above functions have been removed from CO2.js, you will need to use the Sustainability Plugin or your own code for that functionality.

If this change impacts your code, please follow the issue on GitHub and leave a comment if you have any concerns.

You can find details of every release for CO2.js on GitHub, where you’ll also be able find the changelog for this project.

Highlighting emissions in your tools?

If you’re a browser developer or software vendor that’s highlighting carbon emissions in your tools, then we’d love to hear from you and learn together.

If you’re just getting started, Green Web Foundation also offers consulting and advisory services to provide guidance and support to your developers.