# Shopware 6 — Remote Thumbnails

Starting with Shopware 6.6.4, Shopware supports **remote thumbnail generation**. Instead of creating physical thumbnail files on disk during media upload, Shopware generates thumbnail URLs that point to an external service — and smoxy can handle the actual resizing on the fly through its [image manipulation](https://docs.smoxy.eu/en/image-processing/image-processing) feature.

This eliminates the need for pre-generated thumbnails entirely. No more `bin/console media:generate-thumbnails`, no wasted disk space, and instant support for any thumbnail size the storefront requests.

{% hint style="warning" %}
**Disclaimer:** This guide is based on the Shopware 6 developer documentation as of February 2026. Shopware may change the remote thumbnail feature, its configuration options, or the available pattern variables in future releases. Always refer to the [official Shopware documentation](https://developer.shopware.com/docs/guides/plugins/plugins/content/media/remote-thumbnail-generation.html) for the most up-to-date information. smoxy cannot guarantee compatibility with future Shopware changes.
{% endhint %}

### How It Works

Normally, Shopware generates physical thumbnail files (e.g., `product_400x400.jpg`, `product_800x800.jpg`) and stores them in the `/thumbnail/` directory. With remote thumbnails enabled, Shopware skips this step and instead rewrites all thumbnail URLs to match a configurable pattern. That pattern can be set up to produce URLs that smoxy intercepts via a rewrite rule and processes on the fly.

The flow looks like this:

1. A visitor loads a product page in the storefront.
2. Shopware generates a thumbnail URL using the configured pattern (e.g., `/thumbnail/800/media/ab/cd/product.jpg`).
3. The browser requests that URL from smoxy.
4. smoxy matches the URL against a rewrite rule and resizes the original image on the fly.
5. The processed image is delivered and cached by smoxy.

### Prerequisites

* Shopware 6.6.4 or later
* smoxy's [image manipulation](https://docs.smoxy.eu/en/image-processing/image-processing) feature
* A configured rewrite rule in smoxy (see below)

### Step 1: Configure Shopware

Edit the `config/packages/shopware.yaml` file in the Shopware installation and add the remote thumbnail configuration:

```yaml
shopware:
  media:
    remote_thumbnails:
      enable: true
      pattern: '{mediaUrl}/thumbnail/{width}/{mediaPath}?ts={mediaUpdatedAt}'
```

This tells Shopware to generate thumbnail URLs in the following format:

```
https://shop.example.com/thumbnail/800/media/ab/cd/ef/product.jpg?ts=1716882050
```

#### Available Pattern Variables

Shopware provides the following variables for the pattern:

| Variable           | Example                      | Description                                                    |
| ------------------ | ---------------------------- | -------------------------------------------------------------- |
| `{mediaUrl}`       | `https://shop.example.com`   | Base URL of the media storage                                  |
| `{mediaPath}`      | `media/ab/cd/ef/product.jpg` | Relative path to the original image                            |
| `{width}`          | `800`                        | Requested thumbnail width                                      |
| `{height}`         | `800`                        | Requested thumbnail height                                     |
| `{mediaUpdatedAt}` | `1716882050`                 | Unix timestamp of the last media update (acts as cache buster) |

{% hint style="info" %}
**Note:** The `?ts={mediaUpdatedAt}` query parameter does not affect the smoxy rewrite rule match but ensures that browsers and CDN caches serve fresh versions when an image is updated in Shopware.
{% endhint %}

### Step 2: Create a Rewrite Rule in smoxy

In the smoxy dashboard, create a rewrite rule that catches the thumbnail URLs generated by Shopware and routes them through image manipulation.

#### Width Only (Recommended)

This is the simplest and most common setup. Shopware's default thumbnail sizes (400×400, 800×800, 1920×1920) are square, but the storefront `srcset` typically only varies by width with height auto-calculated to preserve the aspect ratio.

**Shopware pattern:**

```yaml
pattern: '{mediaUrl}/thumbnail/{width}/{mediaPath}?ts={mediaUpdatedAt}'
```

**smoxy rewrite rule:**

| Field       | Value                           |
| ----------- | ------------------------------- |
| Regex       | `^/thumbnail/(\d+)/(.*)`        |
| Target Path | `/_sx/img/_/w:$1/q:80/plain/$2` |

A request to `/thumbnail/800/media/ab/cd/ef/product.jpg?ts=1716882050` will:

1. Fetch the original image from `/media/ab/cd/ef/product.jpg` on the origin server.
2. Resize it to 800px width (height auto-calculated from the aspect ratio).
3. Set the output quality to 80%.
4. Deliver the processed image.

#### Width and Height

If both width and height need to be respected (e.g., for strictly sized grid layouts), the pattern can include both dimensions.

**Shopware pattern:**

```yaml
pattern: '{mediaUrl}/thumbnail/{width}x{height}/{mediaPath}?ts={mediaUpdatedAt}'
```

**smoxy rewrite rule:**

| Field       | Value                                   |
| ----------- | --------------------------------------- |
| Regex       | `^/thumbnail/(\d+)x(\d+)/(.*)`          |
| Target Path | `/_sx/img/_/rs:fit:$1:$2/q:80/plain/$3` |

{% hint style="info" %}
**Tip:** Replace `rs:fit` with `rs:fill` if the image should completely fill the given dimensions (cropping excess) instead of fitting within them. See the [resizing types reference](https://docs.smoxy.eu/en/image-processing/resizing-and-cropping#resizing-type) for all available options.
{% endhint %}

### Step 3: Clean Up Existing Thumbnails (Optional)

Once remote thumbnails are working, the existing physical thumbnail files on the server are no longer needed. They can be removed to free up disk space:

```bash
# Remove all generated thumbnails
bin/console media:delete-thumbnails
```

{% hint style="warning" %}
**Important:** Verify that remote thumbnails are working correctly in the storefront before deleting existing thumbnail files. Check the browser's developer tools (Network tab) to confirm that thumbnail requests are being served through smoxy.
{% endhint %}

### Advanced Examples

#### Higher Quality for Large Images

Different quality levels can be applied based on the thumbnail size using two separate rewrite rules:

**Rule 1 — Small thumbnails (low quality, fast loading):**

| Field       | Value                           |
| ----------- | ------------------------------- |
| Regex       | `^/thumbnail/small/(\d+)/(.*)`  |
| Target Path | `/_sx/img/_/w:$1/q:60/plain/$2` |

**Rule 2 — Large thumbnails (high quality):**

| Field       | Value                                  |
| ----------- | -------------------------------------- |
| Regex       | `^/thumbnail/large/(\d+)/(.*)`         |
| Target Path | `/_sx/img/_/w:$1/q:90/sh:0.5/plain/$2` |

This requires two separate Shopware patterns (or a plugin that adjusts the pattern based on the thumbnail context).

#### Smart Cropping for Product Thumbnails

Use smart gravity to automatically focus on the most interesting part of the image when cropping:

**Shopware pattern:**

```yaml
pattern: '{mediaUrl}/thumbnail/{width}x{height}/{mediaPath}?ts={mediaUpdatedAt}'
```

**smoxy rewrite rule:**

| Field       | Value                                         |
| ----------- | --------------------------------------------- |
| Regex       | `^/thumbnail/(\d+)x(\d+)/(.*)`                |
| Target Path | `/_sx/img/_/rs:fill:$1:$2/g:sm/q:80/plain/$3` |

The `g:sm` (smart gravity) option ensures that product images are cropped around the most visually relevant area rather than always from the center.

### Troubleshooting

#### Images Not Loading

* Verify that the Shopware pattern produces URLs that match the smoxy rewrite rule regex. Open a product page, inspect an image in the browser, and check the generated `src` or `srcset` URL.
* Ensure the rewrite rule is active and positioned correctly in the smoxy rule list.

#### Wrong Image Dimensions

* Check whether Shopware is passing `{width}` only or both `{width}` and `{height}` — and make sure the rewrite rule regex matches accordingly.
* If images appear stretched, switch from `rs:force` to `rs:fit` or `rs:fill`.

#### Stale Images After Update

* The `{mediaUpdatedAt}` timestamp in the query string should handle cache invalidation automatically. If stale images persist, a cache purge in smoxy may be necessary.

### Further Reading

* [Image Manipulation Overview](https://docs.smoxy.eu/en/image-processing/image-processing)
* [Resizing & Cropping Reference](https://docs.smoxy.eu/en/image-processing/resizing-and-cropping)
* [Effects & Adjustments Reference](https://docs.smoxy.eu/en/image-processing/effects-and-adjustments)
* [Output, Metadata & Delivery Reference](https://docs.smoxy.eu/en/image-processing/output-metadata-and-delivery)