Automatización de la optimización de imágenes con un pipeline WASM 2025 — Recetas con esbuild y Lightning CSS

Para las personas desarrolladoras web que combinan builds Jamstack con entrega en el edge, la pregunta «¿cuánto trabajo de imágenes debe hacerse en build y cuánto en demanda?» nunca desaparece. En 2025, el ecosistema WASM (WebAssembly) por fin nos da compiladores y optimizadores rápidos que se ejecutan en Node.js sin depender de la GPU y aun así producen derivados de calidad. Esta guía muestra cómo montar un pipeline de compilación alrededor de esbuild y Lightning CSS, reforzado con Squoosh CLI y codificadores AVIF compilados a WASM, y cómo conectarlo íntegramente a CI/CD.

TL;DR

• Bundle WASM en tres capas: (1) compila TypeScript + plugins WASM con esbuild, (2) ejecuta Squoosh CLI en Worker Threads, (3) deja que Lightning CSS genere image-set() automáticamente.
• Reglas declarativas de derivados: define tamaño, formato y calidad en assets.manifest.json y cárgalo desde un plugin de esbuild.
• Reproducibilidad en CI: reutiliza cachés .uasset livianas en lugar de blobs de Git LFS y regenera automáticamente cuando los hashes divergen.
• Validación local primero: combina Playwright con el Comparador de Imágenes para detectar artefactos visuales antes de fusionar.
• Fallbacks y firma: integra perfiles ICC en WebP/AVIF mediante el Convertidor avanzado y conserva un PNG firmado con C2PA como último recurso.

Panorama del pipeline

Controlar los derivados con manifiestos declarativos

Los scripts npm ad-hoc generan conocimiento tácito. Captura la intención en un manifiesto JSON.

{
  "hero-landing": {
    "source": "assets/hero-source.tif",
    "variants": [
      { "format": "avif", "width": 1600, "quality": 0.82 },
      { "format": "webp", "width": 1200, "quality": 0.88 },
      { "format": "jpeg", "width": 800, "quality": 0.92, "icc": "profiles/display-p3.icc" }
    ],
    "responsive": {
      "breakpoints": ["(min-width: 1280px) 1200px", "(min-width: 768px) 65vw", "100vw"],
      "density": ["1x", "2x"]
    }
  }
}

El plugin de esbuild lee este archivo y programa el trabajo WASM en paralelo.

Implementación del plugin de esbuild

// build/plugins/image-pipeline.ts
import { Plugin } from 'esbuild'
import { readFile } from 'node:fs/promises'
import { runPipeline } from '../wasm/run-pipeline'

export const imagePipeline = (): Plugin => ({
  name: 'image-pipeline',
  setup(build) {
    build.onStart(async () => {
      const manifest = JSON.parse(await readFile('assets.manifest.json', 'utf-8'))
      await runPipeline(manifest)
    })
  }
})

runPipeline crea Worker Threads, mantiene la concurrencia a raya y maneja errores sin bloquear la build.

// build/wasm/run-pipeline.ts
import { Worker } from 'node:worker_threads'
import os from 'node:os'

const workerCount = Math.max(1, Math.min(os.cpus().length - 1, 4))

export async function runPipeline(manifest: Record<string, any>) {
  const entries = Object.entries(manifest)
  await Promise.all(entries.map(([id, config]) => dispatchWorker(id, config)))
}

function dispatchWorker(id: string, config: any) {
  return new Promise((resolve, reject) => {
    const worker = new Worker(new URL('./workers/image-worker.ts', import.meta.url), {
      workerData: { id, config }
    })
    worker.once('message', resolve)
    worker.once('error', reject)
    worker.once('exit', code => code !== 0 && reject(new Error(`worker ${id} exited ${code}`)))
  })
}

Dentro del worker, almacena en caché los binarios WASM para evitar inicios fríos repetidos.

// build/wasm/workers/image-worker.ts
import { parentPort, workerData } from 'node:worker_threads'
import { createRequire } from 'node:module'
const require = createRequire(import.meta.url)

const squoosh = require('@squoosh/lib')
const avif = require('@squoosh/avif')

(async () => {
  const { id, config } = workerData
  const { source, variants } = config
  const jobs = variants.map(async variant => {
    const image = await squoosh.ImagePool.fromPath(source)
    await image.encode({
      [variant.format]: {
        quality: Math.round(variant.quality * 100),
        effort: 7
      }
    })
    await image.save(`public/images/${id}-${variant.width}.${variant.format}`)
  })
  await Promise.all(jobs)
  parentPort?.postMessage({ id, ok: true })
})()

Generar CSS automáticamente con Lightning CSS

Para mantener el CSS alineado con el manifiesto, integra Lightning CSS en el pipeline.

// build/styles/picture-plugin.ts
import { readFileSync } from 'node:fs'
import { transform } from 'lightningcss'
import manifest from '../../asset-map.json'

export function injectImageSets(cssPath: string) {
  const css = readFileSync(cssPath)
  const result = transform({
    filename: cssPath,
    code: css,
    drafts: { nesting: true },
    visitor: {
      Rule(rule) {
        if (!rule.selectors.includes('.hero-visual')) return
        const sources = manifest['hero-landing'].imageSet
        rule.declarations.push({
          kind: 'declaration',
          property: 'background-image',
          value: {
            type: 'value',
            value: `image-set(${sources.join(', ')})`
          }
        })
      }
    }
  })
  return result.code
}

Tras la build, Lightning CSS consulta asset-map.json para emitir reglas image-set() y sincronizarlas con los bloques @media. Como el transformador corre en WASM, el hot reload se mantiene ágil.

Detección de diferencias y firma en CI

Los builds WASM son veloces, pero el daño silencioso sigue siendo un riesgo. Refuérzalo en CI.

1. Diferencias visuales: captura la sección hero con Playwright y pásala por el CLI del Comparador de Imágenes para calcular ΔE2000.
2. Metadatos: usa ExifTool y el Convertidor avanzado para comprobar que los perfiles ICC y XMP sobreviven.
3. Firma C2PA: firma el PNG de fallback con el CLI cai y añade la URI de la firma a asset-map.json.

# .github/workflows/build.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build:images
      - run: npm run test:visual
      - run: npm run sign:fallback
      - uses: actions/upload-artifact@v4
        with:
          name: wasm-assets
          path: public/images

Los artefactos reducen el tiempo de rebuild en un 40 % o más. Cuando aparezca un hash inesperado, regenera los derivados y avisa al equipo por Slack.

Buenas prácticas de entrega en el edge

• Keys de caché: evita conmutar a ?format= indiscriminadamente; negocia con Accept.
• Cabeceras: usa public, max-age=31536000, immutable como base y agrega must-revalidate solo al PNG con firma C2PA.
• Fallbacks: si la conversión WASM falla, devuelve un JPEG de alta calidad generado con el Convertidor avanzado desde una función Lambda@Edge.
• Monitoreo: captura LargestContentfulPaint con PerformanceObserver y vigila regresiones cuando cambian los tamaños de los derivados.

Checklist de implementación

• [ ] assets.manifest.json declara todas las reglas de derivados.
• [ ] Los workers WASM limitan la concurrencia según los núcleos disponibles.
• [ ] asset-map.json registra formato, dimensiones y hashes.
• [ ] Playwright + Comparador de Imágenes automatizan la diferencia visual.
• [ ] El Convertidor avanzado se encarga de incrustar ICC y firmar en el flujo de release.
• [ ] La negociación por Accept y los fallbacks están validados en la CDN.

Resumen

Un pipeline con enfoque WASM es más sencillo de aprovisionar que las toolchains nativas y entrega resultados consistentes en CI en la nube. Al centrar el flujo en esbuild y Lightning CSS, y sumar Squoosh y codificadores en WASM, el equipo web puede cerrar la optimización de imágenes durante la build y reducir los costos en ejecución. Con validaciones y firmas automáticas, obtendrás un pipeline equilibrado entre rendimiento y confianza, listo para lanzamientos globales.