pixboost/transformimgs repository overview

⁠TransformImgs

Open Source Image CDN⁠ that provides image transformation API and supports the latest image formats, such as WebP, AVIF and network client hints.

⁠Table of Contents

• Why?⁠
• Features⁠
• Quickstart⁠
• API⁠
• Running⁠
  • Docker⁠
  • Options⁠
  • Running Locally From Source Code⁠
• SaaS⁠
• Performance tests⁠
• Opened tickets for images related features⁠
• Contribute⁠
• License⁠
• Todo⁠

⁠Why?

We wrote a big blog on this⁠, and here is TLDR:

Transformimgs is an image CDN for Web, so API must cover typical use cases, like thumbnails, zoom in product images, etc. Any new API endpoints must solve the above problems.

The goal is to have zero-config API that makes decisions based on the input, so you don't need to provide additional parameters like quality, output format, type of compression, etc.

Therefore, this allows you to configure the integration once. New features, like new image formats, will work with your front end automatically without any changes.

To achieve that goal we should keep API to bare minimum and hide the smartness in the implementation.

⁠Features

• Resize/optimises/crops raster (PNG and JPEG) images.
• AVIF⁠ / WebP⁠ support based on "Accept" header.
• Vary⁠ header support - ready to deploy behind any CDN.
• Responsive images support including high DPI (retina) displays
• Save-Data⁠ support

⁠Quickstart

There is an example of running API behind reverse proxy with integration example in quickstart/ folder.

To run:

cd quickstart
docker-compose up
open https://localhost

⁠API

The API has 4 HTTP endpoints:

• /img/{IMG_URL}/optimise - optimises image
• /img/{IMG_URL}/resize - resizes image
• /img/{IMG_URL}/fit - resize image to the exact size by resizing and cropping it
• /img/{IMG_URL}/asis - returns original image

Docs:

• Swagger-UI⁠ - use API key MjUyMTM3OTQyNw__ which allows to transform any image from pixabay.com
• OpenAPI spec⁠

⁠Running Locally

⁠Docker

The latest docker image published on Docker hub⁠

Starting the server:

$ docker run -p 8080:8080 pixboost/transformimgs [OPTIONS]

To verify:

• Health check: curl http://localhost:8080/health
• Transformation: open http://localhost:8080/img/https://images.unsplash.com/photo-1591769225440-811ad7d6eab3/resize?size=600

⁠Options

Everything below is optional and have sensible defaults.

⁠Running from source code

Prerequisites:

• Go 1.18+ with modules support⁠
• Installed imagemagick v7.0.25+⁠ with AVIF support in /usr/local/bin

$ git clone [email protected]:Pixboost/transformimgs.git
$ cd transformimgs
$ ./run.sh 

⁠SaaS

We run SaaS version at pixboost.com⁠ with generous free tier.

Perks of SaaS version:

• CDN with HTTP/3 support included
• Dashboard with usage monitor
• API Key support with domains allow list
• AWS S3 integration
• API workflows for cache busting and warmup
• Version upgrades

Go modules have been introduced in v6.

⁠Performance tests

There is a JMeter⁠ performance test you can run against a service. To run tests:

• Start a performance test environment:

$ docker-compose -f docker-compose-perf.yml up

• Run JMeter tests:

$ jmeter -n -t perf-test.jmx -l ./results.jmx -e -o ./results

• Run JMeter WebP test:

$ jmeter -n -t perf-test-webp.jmx -l ./results-webp.jmx -e -o ./results-webp

• Run JMeter AVIF test:

$ jmeter -n -t perf-test-avif.jmx -l ./results-avif.jmx -e -o ./results-avif

⁠Opened tickets for images related features

• Safari to support Save-Data⁠
• Safari to support AVIF⁠
• Firefox to support JPEG XL⁠
• Chrome to support JPEG XL⁠
• Safari to support JPEG XL⁠
• Safari to support native lazy loading
  • Implementation⁠
  • Enabled by default⁠

⁠Contribute

Shout out with any ideas. PRs are more than welcome.

⁠License

MIT⁠

⁠Todo

• Add JpegXR support (IE supports WEBP)
• Add Jpeg 2000 support (Safari support WEBP)
• Client Hints⁠ - on hold due to browsers adoption
• Save-Data header⁠ (Added in version 7.0.0)
• SVG support⁠
• Consider using Zopfli⁠ or Brotli⁠ for PNGs
• JpegXL Support since supported by Safari 17
• GIF support (Added in version 6.1.0)