Skip to content

Release guide: CO2.js v0.11

The v0.11.0 release of CO2.js marks a major milestone for the library. It sees the Sustainable Web Design (SWD) model become the default estimation model in the library. In addition, we have introduced scripts to generate global average and margin grid intensity data.

Defaulting to SWD

The Sustainable Web Design model is now the default carbon estimation model for CO2.js.

CO2.js includes two models for calculating digital carbon emissions – the OneByte model, and the Sustainable Web Design model. The OneByte model has been the default model in CO2.js since the library was first created, and has been the default until now. The Sustainable Web Design (SWD) model was added to CO2.js in April, 2022.

The OneByte model is a few years old now, and while the original model used wider systems boundaries a judgement call was made to reduce its scope when it was originally implemented in CO2.js. You can read more about why in this GitHub issue.

With the updates in v0.10.2 making it easier for developers to switch between models, we decided the time was right to change the default estimation model to the more recent SWD version.

What does this change mean for estimates?

Let’s take the very simple code below as a starter:

import { co2 } from '@tgwf/co2'
const carbon = new co2()

This code imports the main CO2.js library and initialises a new carbon object. Prior to v0.11.0, this would use the OneByte model for carbon estimates. Now, it will use the SWD model, and expose the methods available in that model.

What does this mean for carbon estimates using the default initialisation above? Those produced by the OneByte model will be lower than those from Sustainable Web Design for the same amount of data transfer. You can read more about why in the CO2.js docs.

What if you still want to use the OneByte model?

If you want to continue using the OneByte model for carbon estimates, then you can do so by passing in the { model: '1byte' } parameter when initialising CO2.js.

import { co2 } from '@tgwf/co2'
const oneByte = new co2({ model: '1byte' })

Including average and marginal intensity data

Sourcing carbon intensity data shouldn’t be the remit of developers. For that reason, CO2.js now includes yearly average grid intensity data from Ember, as well as marginal intensity data from the UNFCCC (United Nations Framework Convention on Climate Change).

Both sets of data are yearly figures, but they can be useful when making carbon estimates based of energy usage in different scenarios. While average figures are more commonly used in reporting and standards, some specifications like The Green Software Foundation’s Software Carbon Intensity specification use marginal data instead.

You can find the data in two formats – JSON and CommonJS. These can be found in the data/output folder of the CO2.js repository.

Importing grid intensity data

With average and marginal grid intensity data now available in CO2.js, it would be only be right to make this useful to anyone wanting to use such information in their projects. As a result, we have exposed both average and marginal grid intensity data through the CO2.js library.

For example, if we wanted to use the average grid intensity for Australia in our project, we could use the code below:

import { averageIntensity } from '@tgwf/co2';
const { data } = averageIntensity;
const { AUS } = data;
console.log({ AUS })

All countries are represented by their respective Alpha-3 ISO country code.


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

If you are using CO2.js in production then The Green Web Foundation would love to hear from you! Use the contact form on the website to get in touch.