Usage

The badgesize.io service allows you to display the size of any given file which is accessible, whether within your GitHub repository, npm package, CDN service or hosted your own endpoint.

The displayed size is the total size number of bytes of the file when fetched from the original hosting location including any requested compression, if the hosting site doesn't support the requested compression then the size will (most likely) be the full uncompressed size. You can also configure whether the displayed size includes the bytes for any of the returned headers which are never compressed and whether the formatted value is calculated in decimal (base 10) or binary (base 2).The defaults are Binary without any headers included.

To provide better scale while also reducing hosting costs, the files for a specific badge are fetched on-demand with any results internally cached to fulfil any subsequent requests. The caching mechanism uses a combination of cached number of elements in a FIFO style buffering where the minimum cache period is set to 24 hours, while also using any Cache-Control/Expires headers to provide longer periods when known. For example when using a CDN service that returns files from npm packages the internal Cache period and the resulting badge will be set to 1 year to reduce the number of requests made to the service.

General Usage

https://img.badgesize.io/:fileurl[:ext][?:queryArgs]

:fileurl

The filepath can be a relative GitHub URL or any absolute URL, when not hosted within GitHub.com.

The format or the GitHub URL is the same as when you browser it in the shource explorer, minus the blob/ portion.

Typical format is: (:user/:repo/:branch/:path)

:ext

Optional image/result format.svg|.png, when excluded .svg will be assumed. The returned image will ALWAYS be a .svg formatted image even if a .png is requested.

Note: If you want to show the size of an image with either .svg or .png extension then you MUST also append this optional format extension, otherwise the service will strip the matching extension and use the remainder as the "source" filename, which will most likely result in a 404.

:queryArgs

Parameter	Type/Values	Description
compression	`any \| gzip \| brotli`	Request the `:filepath` using the requested compression type, when `any` is used the service will request both `brotli` and `gzip` and it will be up to the `:filepath` hosting service to return it's most appropiate compresstion type. If the hosting service does not support the requested compression format the resulting file size will most likely be the full size of the file. For example, at this point in time, GitHub does not support / return `brotli` compressed content, as such the resulting display file when only requesting `brotli` will be the full raw size of the file.
label	<string>	A string identifying the label you want to include on the badge, when not included the default will be size, or if some form of compression is requested then it will include the compression type gzip size, brotli size or Compressed size
color	A known color or a hexadecimal color representation	Optional background color of the badge, You can specify hexadecimal colors without the dash (i.e. 97ca00) or a known named color. Defaults to brightgreen when not specified.
max	<number> bytes	Optional size limit in bytes, exceeding this limit will generate a red badge. The size is the calculated returned size from the hosting service with or without headers (depending if you have included `hdr` in the `size` query string parameter. This setting overrides the `color` option if specified and the size exceeds the limit. `https://img.badgesize.io/:filepath?max=200000`
softmax	<number> bytes	Optional soft size limit in bytes, exceeding this limit will generate a yellow badge unless the you have also specified max and the size exceeds the max limit. This setting overrides the `color` option if specified and the size exceeds the limit. `https://img.badgesize.io/:filepath?max=200000&softmax=100000`
size	Comma seperated string [`bin\|dec`],[`hdr`]	Identifies how the convert the size into a more human readable format and whether any returned headers should also be included as part of the total number of bytes. `dec` - Use decimal (base-10) calculation `bin` - Use binary (base-2) calculation `hdr` - Include the size of all returned headers as part of the size total Defaults to `bin` with no headers. Any returned headers are never compressed, so these additional bytes will be unaffected by any provided compression.
style	`flat \| flat-square \| plastic \| social`	Optional badge style, defaults to `flat`.
labelColor	A known color or a hexadecimal color representation	Optional background color of the badge, You can specify hexadecimal colors without the dash (i.e. 97ca00) or a known named color.

See Examples

Known differences from previous version

The reported size for the GZip and Brotli compression is based on the size reported by the site / CDN used to fetch the requested file, this provides a more accurate representaiton of the download impact / experience that your end-user / consumers will experience from the previous version (which used local compression).
Does not support PNG response
Does not support JSON response
It uses a longer Cache-Control period to assist with reducing the overall costs of maintaining this service.
Badges are automatically added to images based on the source of the file.
Provides a generic compression type any which can be used to return your site / CDN's default compression algirithm.