Skip to content

docs: rewrite README for plugin monorepo #114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcelometal merged 1 commit into from
Apr 18, 2026
Merged

docs: rewrite README for plugin monorepo #114

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
171 changes: 140 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,61 +1,170 @@
# thumbor-plugins
[![Github Actions - tests](https://github.com/thumbor/thumbor-plugins/actions/workflows/test.yml/badge.svg)](https://github.com/thumbor/thumbor-plugins/actions)

This monorepo contains multiple plugins that should be used on
[Thumbor][thumbor] to add new capabilities, like GifV or Mozjpeg compression.
[![GitHub Actions - tests](https://github.com/thumbor/thumbor-plugins/actions/workflows/test.yml/badge.svg)](https://github.com/thumbor/thumbor-plugins/actions/workflows/test.yml)

Each of the optimizers is released and can be installed separately.
`thumbor-plugins` is a monorepo of independently released
[Thumbor](https://github.com/thumbor/thumbor) optimizers. Each directory under
`thumbor_plugins/optimizers/` is its own Python package, with its own
changelog, tests, and release cycle.

## 📜 List of thumbor-plugins
The repository focuses on small, composable integrations that add image or
media optimization steps to a Thumbor deployment without forcing you to install
a single umbrella package. There is no all-in-one `thumbor-plugins`
distribution for runtime use; install the optimizer packages you actually want
to enable.

You can find the plugins in: https://pypi.org/search/?q=%22thumbor-plugins%22&o=-created
## What's in this repository

## ⚙️ Installation
| Optimizer | PyPI package | Thumbor module | What it does | Trigger | Runtime dependency | Config |
| --------------- | -------------------------------- | ------------------------------------------- | -------------------------------------- | ------------------------------------------- | -------------------------------------------- | ----------------------------------------------------- |
| GifV | `thumbor-plugins-gifv` | `thumbor_plugins.optimizers.gifv` | Converts GIF requests into MP4 or WebM | Requests whose filter chain contains `gifv` | `ffmpeg` | `FFMPEG_PATH` |
| JP2 | `thumbor-plugins-jp2` | `thumbor_plugins.optimizers.jp2` | Writes JPEG 2000 output through Pillow | Requests whose filter chain contains `jp2` | Pillow built with JPEG 2000/OpenJPEG support | `JP2_QUALITY` |
| JPEG Recompress | `thumbor-plugins-jpegrecompress` | `thumbor_plugins.optimizers.jpegrecompress` | Runs `jpeg-recompress` for JPEGs | Automatic for `.jpg` / `.jpeg` | `jpeg-recompress` | `JPEGRECOMPRESS_PATH` |
| MozJPEG | `thumbor-plugins-mozjpeg` | `thumbor_plugins.optimizers.mozjpeg` | Runs `cjpeg` from MozJPEG for JPEGs | Automatic for `.jpg` / `.jpeg` | `cjpeg` from MozJPEG | `MOZJPEG_PATH`, `MOZJPEG_QUALITY` |
| OptiPNG | `thumbor-plugins-optipng` | `thumbor_plugins.optimizers.optipng` | Runs `optipng` for PNGs | Automatic for `.png` | `optipng` | `OPTIPNG_PATH`, `OPTIPNG_LEVEL` |
| PNGCrush | `thumbor-plugins-pngcrush` | `thumbor_plugins.optimizers.pngcrush` | Runs `pngcrush -reduce` for PNGs | Automatic for `.png` | `pngcrush` | `PNGCRUSH_PATH` |
| PNGQuant | `thumbor-plugins-pngquant` | `thumbor_plugins.optimizers.pngquant` | Runs `pngquant` for PNGs | Automatic for `.png` | `pngquant` | `PNGQUANT_PATH`, `PNGQUANT_QUALITY`, `PNGQUANT_SPEED` |

## Installation

Install only the packages you need:

```bash
pip install thumbor-plugins-mozjpeg
pip install thumbor-plugins-pngquant
pip install thumbor-plugins-gifv
```

## 🎯 Usage
Most optimizers are thin wrappers around native binaries, so `pip install` is
only part of the setup. Your Thumbor runtime image or host must also provide
the matching executable, such as `ffmpeg`, `pngquant`, `optipng`, `pngcrush`,
`jpeg-recompress`, or MozJPEG's `cjpeg`.

## Usage in Thumbor

After installing the packages, just add the plugins you need to the OPTIMIZERS
list on your thumbor.conf
After installing a package, add its module to the `OPTIMIZERS` list in
`thumbor.conf`:

```python
OPTIMIZERS = [
'thumbor_plugins.optimizers.mozjpeg',
'thumbor_plugins.optimizers.gifv',
"thumbor_plugins.optimizers.mozjpeg",
"thumbor_plugins.optimizers.pngquant",
"thumbor_plugins.optimizers.gifv",
]

MOZJPEG_PATH = "/opt/mozjpeg/bin/cjpeg"
MOZJPEG_QUALITY = "75"

PNGQUANT_PATH = "/usr/bin/pngquant"
PNGQUANT_QUALITY = "65-80"
PNGQUANT_SPEED = "1"

FFMPEG_PATH = "/usr/bin/ffmpeg"
```

How each optimizer behaves:

- `mozjpeg` and `jpegrecompress` run for JPEG requests.
- `pngquant`, `pngcrush`, and `optipng` run for PNG requests.
- `gifv` runs only when the request filter chain contains `gifv`.
- `jp2` runs when the request filter chain contains `jp2`.

### GifV examples

Convert a GIF into MP4:

```text
/unsafe/filters:gifv()/animated.gif
```

Each optimizer contains parameters that can be used to configure how it runs.
Convert a GIF into WebM:

```text
/unsafe/filters:gifv(webm)/animated.gif
```

## 👍 Contribute
Set a background color for transparent GIF frames:

```text
/unsafe/filters:gifv(mp4):background_color(ff00ff)/animated.gif
```

`background_color(...)` accepts normalized hex values, short hex values, or CSS
color names.

## Repository layout

```text
thumbor_plugins/
optimizers/
<plugin>/
__init__.py
config.py
setup.py
CHANGELOG.md
tests/
test_helpers/
```

thumbor-plugins is an open-source project with many contributors. Join them
[contributing code][contributing].
Each optimizer directory is a standalone distributable package.
That split is intentional: you can ship only the plugins you need, version them
independently, and keep tests isolated per optimizer.

## Development

### Requirements

- Docker for integration tests
- Python 3

The test suite installs `thumbor==7.*` from `test_requirements.txt`.

### Running tests

Run integration and unit tests for a specific optimizer with:

```bash
make test_mozjpeg
make test_pngquant
make test_gifv
```

Run all unit tests with:

```bash
make test_unit
```

To iterate locally on a single optimizer package:

```bash
pip install -r test_requirements.txt
pip install -e thumbor_plugins/optimizers/pngquant
pytest thumbor_plugins/optimizers/pngquant/tests/unit
```

Each optimizer ships its own Dockerfile under
`thumbor_plugins/optimizers/<plugin>/tests/docker/`, and CI uses those
Dockerfiles to build the test matrix.

## 🚨 Breaking change
## Releasing

This repository used to be released under a single package in previous
versions, `thumbor-plugins`.
This repository uses
[release-please](https://github.com/googleapis/release-please) and expects
[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). Because
each optimizer is versioned independently, changes should stay scoped to the
package you are modifying whenever possible.

We broke down into multiple packages to make it easier for developers to
contribute, test, and use different versions.
## Contributing

For example, the mozjpeg optimizer is released on the package
`thumbor-plugins-mozjpeg`, and the Gifv one on the package
`thumbor-plugins-gifv`.
See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow and
[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community guidelines.

## License

## Third Party
This project is licensed under the terms of the [MIT License](LICENSE).

Integration tests uses a bug.png picture by [Marcelo Jorge Vieira][marcelometal]
licensed under [CC-BY-4.0][cc-by-4].
## Third-party assets

[cc-by-4]: https://creativecommons.org/licenses/by/4.0/
[contributing]: https://github.com/thumbor/thumbor-plugins/blob/master/CONTRIBUTING.md
[marcelometal]: https://www.flickr.com/photos/marcelometal/540719764/
[thumbor]: https://github.com/thumbor/thumbor
Integration tests use `bug.png` by [Marcelo Jorge Vieira](https://www.flickr.com/photos/marcelometal/540719764/),
licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
Loading