README

Pre-built, statically compiled binaries for Linux (amd64/musl). Designed to be installed as a Composer package so that vendor/bin/ contains ready-to-use tools on Laravel Cloud (or any Linux environment).

This package includes all the binaries required by spatie/image-optimizer, making it a drop-in solution for image optimization on environments where system packages are not available. Note that svgo is not included as it is a regular npm package and can be installed via npm install -g svgo.

Binaries included

All binaries are statically linked against musl libc (Alpine Linux). They will not run on macOS — this is expected.

Pinned versions

All upstream versions are defined at the top of the Makefile and passed to each Dockerfile via --build-arg. To bump a version, change the single variable in the Makefile.

Installation

composer require mathiasgrimm/laravel-cloud-binaries

Composer will symlink all 11 binaries into vendor/bin/.

Selective installation (faster deploys)

If you only need a few binaries, you can install the package as a dev dependency, copy just the ones you need into your repository, and avoid downloading the full ~93 MB on every deploy:

composer require --dev mathiasgrimm/laravel-cloud-binaries

# Copy only the binaries you need into your project
mkdir -p bin
cp vendor/bin/jpegoptim bin/
cp vendor/bin/optipng bin/
cp vendor/bin/pngquant bin/

# Commit them
git add bin/
git commit -m "Add image optimization binaries"

Then reference them from your application using base_path('bin/jpegoptim') (or whichever path you chose). Since the binaries are committed to your repository, they are available immediately during deployment with no Composer overhead.

To keep your committed binaries in sync automatically when the package is updated, add a post-update-cmd script to your composer.json:

{
    "scripts": {
        "post-update-cmd": [
            "@php -r \"@mkdir('bin', 0755, true);\"",
            "@php -r \"copy('vendor/mathiasgrimm/laravel-cloud-binaries/bin/jpegoptim', 'bin/jpegoptim');\"",
            "@php -r \"copy('vendor/mathiasgrimm/laravel-cloud-binaries/bin/optipng', 'bin/optipng');\"",
            "@php -r \"copy('vendor/mathiasgrimm/laravel-cloud-binaries/bin/pngquant', 'bin/pngquant');\""
        ]
    }
}

After every composer update, the selected binaries are copied into bin/ automatically. Adjust the list to include only the binaries you need. The @php -r syntax ensures the commands work on all platforms (Linux, macOS, and Windows).

Usage

After installation, the binaries are available in vendor/bin/:

vendor/bin/jpegoptim --strip-all image.jpg
vendor/bin/optipng -o2 image.png
vendor/bin/pngquant --quality=65-80 image.png
vendor/bin/cwebp -q 80 image.png -o image.webp
vendor/bin/dwebp image.webp -o image.png
vendor/bin/avifenc image.png image.avif
vendor/bin/avifdec image.avif image.png
vendor/bin/gifsicle -O3 animation.gif -o optimized.gif
vendor/bin/ffmpeg -i input.mp4 -c:v libx264 output.mp4
vendor/bin/ffprobe -v quiet -print_format json -show_format input.mp4
vendor/bin/magick input.png -resize 50% output.png

Note: These are statically compiled Linux (musl) binaries. They will work on Laravel Cloud and other Linux environments but not on macOS or Windows.

Building from source

Prerequisites

• Docker
• make

Build all binaries

make

Binaries are output to the bin/ directory.

Build a single binary

make bin/jpegoptim
make bin/optipng
make bin/pngquant
make bin/cwebp
make bin/dwebp
make bin/avifenc
make bin/avifdec
make bin/gifsicle
make bin/ffmpeg
make bin/ffprobe
make bin/magick

Parallel builds

make -j4

Testing

Verify that all binaries work correctly by running them inside an Alpine Docker container:

make test          # build (if needed) + test
make test-only     # test without rebuilding

Clean up

make clean          # remove bin/ contents
make clean-images   # remove Docker images
make clean-all      # both

How it works

Each tool has its own Dockerfile under <tool>/Dockerfile. The Dockerfiles use multi-stage Alpine builds:

1. Builder stage — installs dependencies, clones source, compiles with static linking flags
2. Final stage — FROM scratch, copies only the static binary

The Makefile orchestrates building the Docker images and extracting the binaries into bin/.