CONFIGURATION

CONFIG OPTIONS

Customize ImageWrangler behavior with a simple YAML configuration file.

imagewrangler.yml

Create a configuration file in your repository root to customize behavior. Invalid values fall back to defaults.

# imagewrangler.yml

# Branch configuration
targetBranch: "main"          # Primary branch to optimize
additionalBranches: []        # Additional branches (glob patterns supported)
  # - "develop"
  # - "feature/*"

directories:
  include: ["**/*"]           # Directories to scan
  exclude:                    # Directories to skip
    - "node_modules/**"
    - ".git/**"
    - "vendor/**"
    - "dist/**"
    - "build/**"

files:
  include:                    # File patterns to include
    - "*.png"
    - "*.jpg"
    - "*.jpeg"
    - "*.gif"
    - "*.webp"
    - "*.svg"
  exclude: []                 # File patterns to skip

optimization:
  lossy: false                # false = lossless (default), true = lossy

  png:
    enabled: true
    lossy: false              # Override global setting for PNG
    compressionLevel: 9       # 0-9 (higher = smaller file, slower)
    usePalette: false         # Convert to palette mode (only when lossy: true)

  jpeg:
    enabled: true
    lossy: false              # Override global setting for JPEG
    quality: 80               # 1-100 (only used when lossy: true)

  webp:
    enabled: true
    lossy: false              # Override global setting for WebP
    quality: 80               # 1-100 (only used when lossy: true)
    effort: 6                 # 1-6 compression effort

  gif:
    enabled: true             # Always lossless

  svg:
    enabled: true             # Always lossless
    multipass: true           # Run multiple optimization passes
    removeViewBox: false      # Keep viewBox for responsiveness

pullRequest:
  minSavings: 1024            # Min bytes saved to create PR
  minKBReduced: 1             # Alternative: min KB saved (easier to read)
  titleTemplate: ""           # Custom PR title template
  labels:                     # Labels to add
    - "optimization"
    - "images"
  autoMerge:
    enabled: false            # Enable auto-merge
    minSavingsPercent: 20     # Min savings % for auto-merge

skip:
  alreadyOptimized: true      # Skip already-optimized images
  minFileSize: 100            # Skip files smaller than this (bytes)

targetBranch — Primary branch

OPTION	TYPE	DEFAULT	DESCRIPTION
targetBranch	string	"main"	Primary branch to optimize (auto-fallback to "master")

additionalBranches — Extra branches

OPTION	TYPE	DEFAULT	DESCRIPTION
additionalBranches	string[]	[]	Additional branches (glob patterns supported)

directories — Directory filtering

OPTION	TYPE	DEFAULT	DESCRIPTION
include	string[]	["*/"]	Directories to scan
exclude	string[]	node_modules/, .git/, vendor/, dist/, build/**	Directories to skip

files — File patterns

OPTION	TYPE	DEFAULT	DESCRIPTION
include	string[]	[".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"]	File patterns to include
exclude	string[]	[]	File patterns to skip

optimization — Per-format settings

PNG

OPTION	TYPE	DEFAULT	DESCRIPTION
enabled	boolean	true	Enable PNG optimization
compressionLevel	number	9	Compression (0-9)
usePalette	boolean	true	Convert to palette when possible

JPEG

OPTION	TYPE	DEFAULT	DESCRIPTION
enabled	boolean	true	Enable JPEG optimization
quality	number	80	Quality (1-100, only when lossy: true)

MozJPEG encoder is always used internally for optimal compression.

WebP

OPTION	TYPE	DEFAULT	DESCRIPTION
enabled	boolean	true	Enable WebP optimization
quality	number	80	Quality (1-100)

GIF

OPTION	TYPE	DEFAULT	DESCRIPTION
enabled	boolean	true	Enable GIF optimization

SVG

OPTION	TYPE	DEFAULT	DESCRIPTION
enabled	boolean	true	Enable SVG optimization
multipass	boolean	true	Multiple optimization passes
removeViewBox	boolean	false	Remove viewBox attribute

pullRequest — PR behavior

OPTION	TYPE	DEFAULT	DESCRIPTION
minSavings	number	1024	Min bytes saved to create PR
minKBReduced	number	—	Alternative: min KB saved (overrides minSavings)
titleTemplate	string	—	Custom PR title template
labels	string[]	["optimization", "images"]	Labels to add
autoMerge.enabled	boolean	false	Enable auto-merge
autoMerge.minSavingsPercent	number	20	Min savings % for auto-merge

skip — Skip conditions

OPTION	TYPE	DEFAULT	DESCRIPTION
alreadyOptimized	boolean	true	Skip already-optimized images
minFileSize	number	100	Skip files smaller than this (bytes)