imagex

Documentation

Overview

Package imagex provides image decode/resize/encode helpers and an opt-in responsive-image pipeline for SSR pages and uploads.

Supports JPEG/PNG encode via the standard library, WebP decode via golang.org/x/image/webp, and WebP encode via the pure-Go github.com/deepteams/webp library (no CGO).

Transform is the primitive. Pipeline mounts GET /_irmik/img plus an {{ img }} template helper (frontend SSR). Variants / WriteVariants encode allowlisted widths at upload time (admin). Nothing here is wired by irmik.New.

Opt-in: import only when processing images.

Index

• Variables
• func Resize(img image.Image, maxW, maxH int) image.Image
• func Transform(src io.Reader, opts Options) ([]byte, string, error)
• func WriteVariants(destDir, name string, src io.Reader, widths []int, opts Options) (map[int]string, error)
• type Format
• type Options
• type Pipeline
  • func (p *Pipeline) FuncMap() template.FuncMap
  • func (p *Pipeline) Handler() (gin.HandlerFunc, error)
  • func (p *Pipeline) Img(src string, attrs ...any) (template.HTML, error)
  • func (p *Pipeline) Mount(r gin.IRoutes) error
• type Variant
  • func Variants(src io.Reader, widths []int, opts Options) ([]Variant, error)

Variables

var DefaultWidths = []int{375, 768, 1440}

DefaultWidths is the allowlist used when Pipeline.Widths is empty.

Functions

func Resize

func Resize(img image.Image, maxW, maxH int) image.Image

Resize returns a resized image without encoding.

func Transform

func Transform(src io.Reader, opts Options) ([]byte, string, error)

Transform decodes src (JPEG/PNG/GIF/WebP), optionally resizes, and encodes.

func WriteVariants

func WriteVariants(destDir, name string, src io.Reader, widths []int, opts Options) (map[int]string, error)

WriteVariants writes name-{width}.ext under destDir (e.g. photo-375.webp). name is sanitized to a single path segment; extension follows opts.Format.

Types

type Format

type Format string

Format is an output encoding.

const (
	JPEG Format = "jpeg"
	PNG  Format = "png"
	// WEBP is lossy WebP encode (pure Go; Quality maps to encoder quality).
	WEBP Format = "webp"
)

type Options

type Options struct {
	// MaxWidth / MaxHeight constrain dimensions (preserving aspect). 0 = unlimited.
	MaxWidth  int
	MaxHeight int
	Format    Format
	// Quality for JPEG/WebP (1-100, default 85).
	Quality int
}

Options controls resize/encode.

type Pipeline

type Pipeline struct {
	// Root is the filesystem root for source images (e.g. "./public").
	Root string
	// Path is the handler route (default /_irmik/img).
	Path string
	// Widths is the allowlist of srcset widths (default 375, 768, 1440).
	Widths []int
	// Format is the encoded variant format (default WEBP).
	Format Format
	// Quality for JPEG/WebP (default 80).
	Quality int
	// CacheDir, when set, stores encoded variants on disk.
	CacheDir string
	// MaxSourceBytes caps a source file (default 8 MiB).
	MaxSourceBytes int64
	// contains filtered or unexported fields
}

Pipeline is an opt-in responsive image optimizer.

Mount it on the Gin engine and merge FuncMap into MountPages so templates can emit srcset. Source files must live under Root; remote URLs are rejected.

func (*Pipeline) FuncMap

func (p *Pipeline) FuncMap() template.FuncMap

FuncMap returns {{ img src attrs? }} for html/template.

{{ img "/hero.jpg" }}
{{ img "/hero.jpg" "Alt text" }}
{{ img "/hero.jpg" (dict "alt" "Hero" "width" 1440 "height" 810 "priority" true) }}

priority omits loading=lazy and sets fetchpriority=high (LCP / hero).

func (*Pipeline) Handler

func (p *Pipeline) Handler() (gin.HandlerFunc, error)

Handler returns the on-demand optimizer. Query: src=/file.jpg&w=375

func (*Pipeline) Img

func (p *Pipeline) Img(src string, attrs ...any) (template.HTML, error)

Img emits a responsive <img> with srcset against this pipeline.

func (*Pipeline) Mount

func (p *Pipeline) Mount(r gin.IRoutes) error

Mount registers GET Path on r. Root must be set.

type Variant

type Variant struct {
	Width       int
	Bytes       []byte
	ContentType string
}

Variant is one encoded size from Variants.

func Variants

func Variants(src io.Reader, widths []int, opts Options) ([]Variant, error)

Variants encodes src once per width (aspect preserved). Use at upload time so admin thumbnails exist before the first view. Widths must be > 0.