feat(asset-server-plugin): add background color query param for transparent images (#4999)

Ryrahul · web-flow · commit 0fec7bca0ad0 · 2026-08-04T08:51:07.000+02:00
diff --git a/packages/asset-server-plugin/src/asset-server.ts b/packages/asset-server-plugin/src/asset-server.ts
@@ -6,7 +6,7 @@ import fs from 'fs-extra';
 import mime from 'mime-types';
 import path from 'path';
 
-import { getValidFormat } from './common';
+import { getValidBackgroundColor, getValidFormat } from './common';
 import { ImageTransformParameters, ImageTransformStrategy } from './config/image-transform-strategy';
 import { S3AssetStorageStrategy } from './config/s3-asset-storage-strategy';
 import { ASSET_SERVER_PLUGIN_INIT_OPTIONS, DEFAULT_CACHE_HEADER, loggerCtx } from './constants';
@@ -199,6 +199,7 @@ export class AssetServer {
         const fpx = +queryParams.fpx || undefined;
         const fpy = +queryParams.fpy || undefined;
         const format = getValidFormat(queryParams.format);
+        const backgroundColor = getValidBackgroundColor(queryParams.bg);
 
         return {
             width,
@@ -209,14 +210,16 @@ export class AssetServer {
             fpx,
             fpy,
             preset: queryParams.preset,
+            backgroundColor,
         };
     }
 
     private getFileNameFromParameters(filePath: string, params: ImageTransformParameters): string {
-        const { width: w, height: h, mode, preset, fpx, fpy, format, quality: q } = params;
+        const { width: w, height: h, mode, preset, fpx, fpy, format, quality: q, backgroundColor } = params;
         /* eslint-disable @typescript-eslint/restrict-template-expressions */
         const focalPoint = fpx && fpy ? `_fpx${fpx}_fpy${fpy}` : '';
         const quality = q ? `_q${q}` : '';
+        const bg = backgroundColor ? `_bg${backgroundColor.replace('#', '')}` : '';
         const imageFormat = getValidFormat(format);
         let imageParamsString = '';
         if (w || h) {
@@ -238,6 +241,9 @@ export class AssetServer {
         if (quality) {
             imageParamsString += quality;
         }
+        if (bg) {
+            imageParamsString += bg;
+        }
 
         const decodedReqPath = this.sanitizeFilePath(filePath);
         if (imageParamsString !== '') {
diff --git a/packages/asset-server-plugin/src/common.ts b/packages/asset-server-plugin/src/common.ts
@@ -40,3 +40,19 @@ export function getValidFormat(format?: unknown): ImageTransformFormat | undefin
             return undefined;
     }
 }
+
+/**
+ * Validates and normalizes a background color hex string.
+ * Accepts 3, 4, 6, or 8 character hex strings (with or without `#` prefix).
+ * Returns the normalized hex string with `#` prefix, or `undefined` if invalid.
+ */
+export function getValidBackgroundColor(input?: unknown): string | undefined {
+    if (typeof input !== 'string' || input.length === 0) {
+        return undefined;
+    }
+    const hex = input.startsWith('#') ? input.slice(1) : input;
+    if (/^[0-9a-fA-F]{3,4}$|^[0-9a-fA-F]{6}$|^[0-9a-fA-F]{8}$/.test(hex)) {
+        return `#${hex.toLowerCase()}`;
+    }
+    return undefined;
+}
diff --git a/packages/asset-server-plugin/src/config/image-transform-strategy.ts b/packages/asset-server-plugin/src/config/image-transform-strategy.ts
@@ -20,6 +20,15 @@ export interface ImageTransformParameters {
     fpx: number | undefined;
     fpy: number | undefined;
     preset: string | undefined;
+    /**
+     * @description
+     * A hex color string (e.g. `'#ffffff'`) to be used as the background color
+     * for images with alpha transparency. The alpha channel will be merged with
+     * this color using Sharp's `flatten()` method.
+     *
+     * @since 3.8.0
+     */
+    backgroundColor: string | undefined;
 }
 
 /**
diff --git a/packages/asset-server-plugin/src/config/preset-only-strategy.ts b/packages/asset-server-plugin/src/config/preset-only-strategy.ts
@@ -1,4 +1,4 @@
-import { ImageTransformFormat } from '../types';
+import { HexColorString, ImageTransformFormat } from '../types';
 
 import {
     GetImageTransformParametersArgs,
@@ -42,6 +42,22 @@ export interface PresetOnlyStrategyOptions {
      * @default false
      */
     allowFocalPoint?: boolean;
+    /**
+     * @description
+     * Whether to allow the background color to be specified in the URL.
+     * If omitted (default), the `bg` parameter is dropped.
+     * If set to an array of hex color strings (e.g. `['#ffffff', '#000000']`),
+     * only those colors are permitted — keeping the cache key space bounded.
+     * If set to `'any'`, any valid hex color is accepted (explicit opt-in to an
+     * unbounded cache surface).
+     *
+     * Comparison is case-insensitive, so `'#FFFFFF'` and `'#ffffff'` are
+     * treated as the same entry.
+     *
+     * @default undefined
+     * @since 3.8.0
+     */
+    permittedBackgroundColors?: HexColorString[] | 'any';
 }
 
 /**
@@ -73,6 +89,7 @@ export interface PresetOnlyStrategyOptions {
  *     permittedQuality: [0, 50, 75, 85, 95],
  *     permittedFormats: ['jpg', 'webp', 'avif'],
  *     allowFocalPoint: true,
+ *     permittedBackgroundColors: ['#ffffff', '#000000'],
  *   }),
  * });
  * ```
@@ -107,6 +124,23 @@ export class PresetOnlyStrategy implements ImageTransformStrategy {
             fpx: this.options.allowFocalPoint ? input.fpx : undefined,
             fpy: this.options.allowFocalPoint ? input.fpy : undefined,
             preset: input.preset,
+            backgroundColor: this.getPermittedBackgroundColor(input.backgroundColor),
         };
     }
+
+    private getPermittedBackgroundColor(input: string | undefined): string | undefined {
+        if (!input) {
+            return undefined;
+        }
+        const permitted = this.options.permittedBackgroundColors;
+        if (!permitted) {
+            return undefined;
+        }
+        if (permitted === 'any') {
+            return input;
+        }
+        const normalise = (c: string) => c.toLowerCase();
+        const normalised = normalise(input);
+        return permitted.some(c => normalise(c) === normalised) ? input : undefined;
+    }
 }
diff --git a/packages/asset-server-plugin/src/transform-image.spec.ts b/packages/asset-server-plugin/src/transform-image.spec.ts
@@ -1,6 +1,9 @@
+import sharp from 'sharp';
 import { describe, expect, it } from 'vitest';
 
-import { Dimensions, Point, resizeToFocalPoint } from './transform-image';
+import { getValidBackgroundColor } from './common';
+import { PresetOnlyStrategy } from './config/preset-only-strategy';
+import { Dimensions, Point, resizeToFocalPoint, transformImage } from './transform-image';
 
 describe('resizeToFocalPoint', () => {
     it('no resize, crop left', () => {
@@ -67,3 +70,189 @@ describe('resizeToFocalPoint', () => {
         });
     });
 });
+
+describe('getValidBackgroundColor', () => {
+    it('accepts 6-char hex without #', () => {
+        expect(getValidBackgroundColor('ffffff')).toBe('#ffffff');
+    });
+
+    it('accepts 6-char hex with #', () => {
+        expect(getValidBackgroundColor('#F0A703')).toBe('#f0a703');
+    });
+
+    it('accepts 3-char shorthand hex', () => {
+        expect(getValidBackgroundColor('fff')).toBe('#fff');
+    });
+
+    it('accepts 8-char hex with alpha', () => {
+        expect(getValidBackgroundColor('ffffff80')).toBe('#ffffff80');
+    });
+
+    it('accepts 4-char shorthand hex with alpha', () => {
+        expect(getValidBackgroundColor('fff8')).toBe('#fff8');
+    });
+
+    it('returns undefined for empty string', () => {
+        expect(getValidBackgroundColor('')).toBeUndefined();
+    });
+
+    it('returns undefined for non-string input', () => {
+        expect(getValidBackgroundColor(undefined)).toBeUndefined();
+        expect(getValidBackgroundColor(123)).toBeUndefined();
+        expect(getValidBackgroundColor(null)).toBeUndefined();
+    });
+
+    it('returns undefined for invalid hex characters', () => {
+        expect(getValidBackgroundColor('gggggg')).toBeUndefined();
+        expect(getValidBackgroundColor('xyz')).toBeUndefined();
+    });
+
+    it('returns undefined for wrong length hex', () => {
+        expect(getValidBackgroundColor('ff')).toBeUndefined();
+        expect(getValidBackgroundColor('fffff')).toBeUndefined();
+        expect(getValidBackgroundColor('fffffffff')).toBeUndefined();
+    });
+});
+
+describe('transformImage with backgroundColor', () => {
+    function createTestPngWithAlpha(width: number, height: number): Promise<Buffer> {
+        return sharp({
+            create: {
+                width,
+                height,
+                channels: 4,
+                background: { r: 255, g: 0, b: 0, alpha: 0.5 },
+            },
+        })
+            .png()
+            .toBuffer();
+    }
+
+    it('flattens alpha channel with specified background color', async () => {
+        const input = await createTestPngWithAlpha(10, 10);
+        const result = await transformImage(input, {
+            width: 10,
+            height: 10,
+            mode: 'resize',
+            quality: undefined,
+            format: 'png',
+            fpx: undefined,
+            fpy: undefined,
+            preset: undefined,
+            backgroundColor: '#ffffff',
+        });
+        const buffer = await result.toBuffer();
+        const { channels, hasAlpha } = await sharp(buffer).metadata();
+        expect(channels).toBe(3);
+        expect(hasAlpha).toBe(false);
+    });
+
+    it('preserves alpha channel when no backgroundColor is set', async () => {
+        const input = await createTestPngWithAlpha(10, 10);
+        const result = await transformImage(input, {
+            width: 10,
+            height: 10,
+            mode: 'resize',
+            quality: undefined,
+            format: 'png',
+            fpx: undefined,
+            fpy: undefined,
+            preset: undefined,
+            backgroundColor: undefined,
+        });
+        const buffer = await result.toBuffer();
+        const { channels, hasAlpha } = await sharp(buffer).metadata();
+        expect(channels).toBe(4);
+        expect(hasAlpha).toBe(true);
+    });
+});
+
+describe('PresetOnlyStrategy permittedBackgroundColors', () => {
+    const presets = [{ name: 'thumb', width: 100, height: 100, mode: 'crop' as const }];
+    const baseInput = {
+        width: undefined,
+        height: undefined,
+        mode: undefined,
+        quality: undefined,
+        format: undefined,
+        fpx: undefined,
+        fpy: undefined,
+        preset: 'thumb',
+        backgroundColor: '#ffffff',
+    };
+
+    it('drops backgroundColor when permittedBackgroundColors is omitted', () => {
+        const strategy = new PresetOnlyStrategy({ defaultPreset: 'thumb' });
+        const result = strategy.getImageTransformParameters({
+            input: baseInput,
+            availablePresets: presets,
+            req: {} as any,
+        });
+        expect(result.backgroundColor).toBeUndefined();
+    });
+
+    it('allows any backgroundColor when set to "any"', () => {
+        const strategy = new PresetOnlyStrategy({
+            defaultPreset: 'thumb',
+            permittedBackgroundColors: 'any',
+        });
+        const result = strategy.getImageTransformParameters({
+            input: baseInput,
+            availablePresets: presets,
+            req: {} as any,
+        });
+        expect(result.backgroundColor).toBe('#ffffff');
+    });
+
+    it('allows a whitelisted backgroundColor', () => {
+        const strategy = new PresetOnlyStrategy({
+            defaultPreset: 'thumb',
+            permittedBackgroundColors: ['#ffffff', '#000000'],
+        });
+        const result = strategy.getImageTransformParameters({
+            input: baseInput,
+            availablePresets: presets,
+            req: {} as any,
+        });
+        expect(result.backgroundColor).toBe('#ffffff');
+    });
+
+    it('drops a non-whitelisted backgroundColor', () => {
+        const strategy = new PresetOnlyStrategy({
+            defaultPreset: 'thumb',
+            permittedBackgroundColors: ['#000000'],
+        });
+        const result = strategy.getImageTransformParameters({
+            input: baseInput,
+            availablePresets: presets,
+            req: {} as any,
+        });
+        expect(result.backgroundColor).toBeUndefined();
+    });
+
+    it('whitelist comparison is case-insensitive', () => {
+        const strategy = new PresetOnlyStrategy({
+            defaultPreset: 'thumb',
+            permittedBackgroundColors: ['#FFFFFF'],
+        });
+        const result = strategy.getImageTransformParameters({
+            input: { ...baseInput, backgroundColor: '#ffffff' },
+            availablePresets: presets,
+            req: {} as any,
+        });
+        expect(result.backgroundColor).toBe('#ffffff');
+    });
+
+    it('whitelist comparison is case-insensitive with # prefix', () => {
+        const strategy = new PresetOnlyStrategy({
+            defaultPreset: 'thumb',
+            permittedBackgroundColors: ['#ffffff'],
+        });
+        const result = strategy.getImageTransformParameters({
+            input: { ...baseInput, backgroundColor: '#ffffff' },
+            availablePresets: presets,
+            req: {} as any,
+        });
+        expect(result.backgroundColor).toBe('#ffffff');
+    });
+});
diff --git a/packages/asset-server-plugin/src/transform-image.ts b/packages/asset-server-plugin/src/transform-image.ts
@@ -24,6 +24,12 @@ export async function transformImage(
     }
 
     const image = sharp(originalImage).rotate();
+
+    // Merge alpha transparency channel with the specified background color
+    if (parameters.backgroundColor) {
+        image.flatten({ background: parameters.backgroundColor });
+    }
+
     try {
         await applyFormat(image, parameters.format, parameters.quality);
     } catch (e: any) {
diff --git a/packages/asset-server-plugin/src/types.ts b/packages/asset-server-plugin/src/types.ts
@@ -9,6 +9,20 @@ import { ImageTransformStrategy } from './config/image-transform-strategy';
 
 export type ImageTransformFormat = 'jpg' | 'jpeg' | 'png' | 'webp' | 'avif';
 
+/**
+ * @description
+ * A `#`-prefixed hex color string, e.g. `'#ffffff'` or `'#000'`.
+ * Full hex-char validation at the type level is not feasible because
+ * TypeScript's template literal unions exceed compiler limits for
+ * 6- and 8-char hex strings. The `#` prefix is enforced at compile time;
+ * hex-character and length validation is handled at runtime by
+ * `getValidBackgroundColor()`.
+ *
+ * @docsCategory core plugins/AssetServerPlugin
+ * @since 3.8.0
+ */
+export type HexColorString = `#${string}`;
+
 /**
  * @description
  * Specifies the way in which an asset preview image will be resized to fit in the
