<!--
  canonical-url: https://www.avonture.be/blog/assets-minification
  published:     2026-04-13
  This is a static plain-Markdown mirror generated at build time.
  Visit the canonical URL above for the fully rendered page, with images and interactive components.
-->

# Streamline Your Frontend - Minifying Assets with Docker, Bash, and YAML

> Drop the heavy Node toolchains. Build a fast, dependency-free asset minification pipeline using a declarative YAML manifest, Bash, and Docker.

---
![Streamline Your Frontend - Minifying Assets with Docker, Bash, and YAML](/img/v2/minification.webp)

**TL;DR**This guide demonstrates how to build a clean, modular, and blazing-fast asset pipeline without polluting your host machine. By combining a declarative YAML manifest, a straightforward Bash orchestrator, and a Dockerized Go-based minifier (`tdewolff/minify`), you get reproducible, isolated builds. It is the perfect setup for projects that require a lean, Docker-first approach to frontend optimization.

In modern web development, keeping your CSS and JavaScript files lean is crucial for performance. While heavy-duty bundlers like Webpack or Vite are great for complex apps, sometimes you just need a simple, portable way to concatenate and minify files without installing a massive Node.js ecosystem on your local machine or CI/CD runner.

Today, we will build a custom build pipeline using:

1. **YAML** to define our asset bundles.
2. **Bash** to orchestrate the file concatenation.
3. **Docker** to perform the actual minification using high-performance tools.

## Running It

Once the manifest and script are in place (covered below), the whole pipeline is one command:

![Running the minification](./images/running.png)

Yeah, it just took five seconds (downloading the Docker image included).

## Why This Approach?

1. **No Node Dependencies**: You don't need a `package.json` or a `node_modules` folder. The minification engine lives inside a Docker container.
2. **Blazing Fast**: `tdewolff/minify` is written in Go. It is significantly faster than many JavaScript-based minifiers.
3. **Declarative**: Adding a new file to your CSS bundle is as simple as adding one line to your `manifest.yaml`.
4. **Consistency**: Because we use Docker, the minification result will be exactly the same on your local machine, your colleague's laptop, and your production CI server.

## The Architecture

Our workflow is really (really!) simple:

1. A Bash script reads a `manifest.yaml` file.
2. It gathers the source files and merges them into a single temporary file.
3. It triggers a Docker container that runs the [minify](https://github.com/tdewolff/minify) engine to compress the code.

### 1. The Configuration (`manifest.yaml`)

First, we need a way to tell our script which files belong together. This YAML structure allows you to define multiple bundles for both CSS and JS.

Here is what we need:

**manifest.yaml**

```yaml
bundles:
  - name: "Main Styles"
    type: "css"
    output: "dist/assets/app.min.css"
    inputs:
      - "public/assets/css/components.css"
      - "public/assets/css/layout.css"
      - "public/assets/css/reset.css"
      - "public/assets/css/variables.css"
  - name: "App Logic"
    type: "js"
    output: "dist/assets/bundle.min.js"
    inputs:
      - "public/assets/js/api.js"
      - "public/assets/js/main.js"
      - "public/assets/js/utils.js"
```

We've two parts, one for CSS and one for JS, and we'll define two things

1. The name of our target file (f.i. we are saying the minified CSS file will be `dist/assets/app.min.css`)
2. A list of input files

### 2. The Orchestrator Script (`build.sh`)

This Bash script uses `yq` (a lightweight YAML processor; think of it as the YAML cousin of [`jq`](/blog/linux-jq)) to parse our manifest. It concatenates the files and then calls the Docker image `[tdewolff/minify](https://hub.docker.com/r/tdewolff/minify)` to handle the heavy lifting. So, we won't pollute our system with additional dependencies — just one small Docker image.

### 3. How to Run It

#### Prerequisites

1. **Docker**: Installed and running.
2. **yq**: A portable command-line YAML processor. You can install by running `sudo apt-get update && sudo apt-get install yq` if you don't have it yet.

#### Set-up

For this tutorial, let's create a few example files. To do this, please start a new terminal and run this long command:

```txt
mkdir /tmp/minification && cd $_ && \
mkdir -p public/assets/css public/assets/js dist/assets && \
cat << 'EOF' > public/assets/css/reset.css
html, body { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: sans-serif; line-height: 1.5; }
EOF
cat << 'EOF' > public/assets/css/variables.css
:root {
    --primary-color: #3498db;
    --secondary-color: #2ecc71;
    --dark-bg: #2c3e50;
    --light-text: #ecf0f1;
}
EOF
cat << 'EOF' > public/assets/css/layout.css
.container { width: 90%; margin: 0 auto; max-width: 1200px; }
.flex-row { display: flex; gap: 20px; flex-wrap: wrap; }
header { background: var(--dark-bg); color: var(--light-text); padding: 2rem; }
EOF
cat << 'EOF' > public/assets/css/components.css
.btn { padding: 10px 20px; border: none; border-radius: 5px; cursor: pointer; }
.btn-primary { background-color: var(--primary-color); color: white; }
.btn-primary:hover { filter: brightness(1.1); }
EOF
cat << 'EOF' > public/assets/js/utils.js
const logger = (msg) => {
    const timestamp = new Date().toISOString();
    console.log(`[${timestamp}] INFO: ${msg}`);
};
EOF
cat << 'EOF' > public/assets/js/api.js
async function fetchData(endpoint) {
    logger(`Fetching data from /api/${endpoint}`);
    const response = await fetch(`/api/${endpoint}`);
    return await response.json();
}
EOF
cat << 'EOF' > public/assets/js/main.js
document.addEventListener('DOMContentLoaded', () => {
    logger('Application initialized');
    const appContainer = document.querySelector('.container');
    if(appContainer) {
        appContainer.innerHTML += '<p>Assets loaded successfully.</p>';
    }
});
EOF
echo "Directory structure and files created successfully."
```

This instruction will create a new `/tmp/minification` folder and automate the creation of a few files:

```tree
├── dist
│   └── assets
└── public
    └── assets
        ├── css
        │   ├── components.css
        │   ├── layout.css
        │   ├── reset.css
        │   └── variables.css
        └── js
            ├── api.js
            ├── main.js
            └── utils.js
```

##### Now, please create the manifest and the script

This done, please finish the set-up by creating the `/tmp/minification/manifest.yaml` manifest file:

**manifest.yaml**

```yaml
bundles:
  - name: "Main Styles"
    type: "css"
    output: "dist/assets/app.min.css"
    inputs:
      - "public/assets/css/components.css"
      - "public/assets/css/layout.css"
      - "public/assets/css/reset.css"
      - "public/assets/css/variables.css"
  - name: "App Logic"
    type: "js"
    output: "dist/assets/bundle.min.js"
    inputs:
      - "public/assets/js/api.js"
      - "public/assets/js/main.js"
      - "public/assets/js/utils.js"
```

And, too, please create the `/tmp/minification/build.sh` Bash script:

**build.sh**

```bash
#!/bin/bash

# Ensure yq is installed
if ! command -v yq &> /dev/null; then
    echo "Error: 'yq' is not installed."
    exit 1
fi

CONFIG_FILE="manifest.yaml"
DOCKER_IMAGE="tdewolff/minify:latest"

echo "--- Starting Build Process ---"

build_failed=0

# Create dist directory
mkdir -p dist/assets

# Iterate through bundles - Added -r flag to all yq calls
bundle_count=$(yq -r '.bundles | length' "$CONFIG_FILE")

for ((i=0; i<bundle_count; i++)); do
    # Using -r to get raw strings without quotes
    NAME=$(yq -r ".bundles[$i].name" "$CONFIG_FILE")
    TYPE=$(yq -r ".bundles[$i].type" "$CONFIG_FILE")
    OUTPUT=$(yq -r ".bundles[$i].output" "$CONFIG_FILE")

    echo "Processing Bundle: $NAME [$TYPE]"

    TEMP_FILE="temp_bundle.$TYPE"
    rm -f "$TEMP_FILE"

    input_count=$(yq -r ".bundles[$i].inputs | length" "$CONFIG_FILE")
    for ((j=0; j<input_count; j++)); do
        INPUT_PATH=$(yq -r ".bundles[$i].inputs[$j]" "$CONFIG_FILE")

        # Now INPUT_PATH is "public/assets/css/reset.css" (no literal quotes)
        if [[ -f "$INPUT_PATH" ]]; then
            cat "$INPUT_PATH" >> "$TEMP_FILE"
            echo "  + Added $INPUT_PATH"
        else
            echo "  ! Warning: File $INPUT_PATH not found. Skipping."
        fi
    done

    if [[ -f "$TEMP_FILE" ]]; then
        echo "  > Minifying..."
        # We ensure the output directory exists for this specific file
        mkdir -p "$(dirname "$OUTPUT")"

        if docker run --rm -v "$(pwd):/src" "$DOCKER_IMAGE" \
            --type="$TYPE" \
            "/src/$TEMP_FILE" > "$OUTPUT"; then
            rm "$TEMP_FILE"
            echo "  ✓ Generated: $OUTPUT"
        else
            echo "  × Error: minification failed for bundle $NAME." >&2
            build_failed=1
        fi
    else
        echo "  × Error: No input files found for bundle $NAME." >&2
        build_failed=1
    fi
done

if [[ "$build_failed" -eq 1 ]]; then
    echo "--- Build Failed ---" >&2
    exit 1
fi

echo "--- Build Complete ---"
```

Last thing is to make it executable (`chmod +x /tmp/minification/build.sh`).

#### Execution

You're now ready. Simply run `./build.sh` to start the concatenation and the minification — the exact command behind the screenshot at the top of this article.

##### Look at the Docker image flags

Surf to [tdewolff/minify](https://hub.docker.com/r/tdewolff/minify) and look for the [demo site](https://go.tacodewolff.nl/minify), the [CLI options](https://github.com/tdewolff/minify/tree/master/cmd/minify) and docs.

## Conclusion

By combining the scripting power of Bash with the isolation of Docker, we've created a robust asset pipeline. This setup is perfect for static sites, legacy PHP projects, or any environment where you want to keep your development tooling as lightweight as possible.

Minified assets are only half of the performance story, though: images are usually the heaviest part of a page. See [Running some checks on your Docusaurus images](/blog/docusaurus-check-images) for the automated audit I run on mine.
