Optical Center
Playground

    Warning codes

    Every adapter emits stable codes so you can grep them in logs, filter them in your CI, or promote them to errors with --strict.

    Codes

    Code Meaning
    OPTICAL_DYNAMIC_SVG A child or attribute of the SVG is dynamic (variable, expression). The plugin bailed out because it could not prove the markup at build time.
    OPTICAL_SPREAD_PROPS The wrapper or SVG used a spread attribute. A spread might inject the optical-center marker at runtime, so the plugin cannot statically decide whether to transform.
    OPTICAL_MISSING_VIEWBOX The SVG has neither a viewBox nor a width/height pair. There is no coordinate system to shift.
    OPTICAL_VIEWBOX_DERIVED The viewBox was derived from width/height attributes. The transform still works, but the result is less accurate than for an explicit viewBox.
    OPTICAL_CLIP_DETECTED The shifted viewBox may clip painted pixels. Common on icons with paint at the very edge of the viewBox. Inspect the output; consider padding the source SVG.
    OPTICAL_RASTERIZE_FAILED resvg could not parse the SVG. The file may be malformed or use features resvg does not support.
    OPTICAL_CACHE_WRITE_FAIL The cache directory is not writable. The compute still succeeded; only the disk write was skipped.
    OPTICAL_VERSION_MISMATCH A cached entry came from a different algorithm version. The entry was discarded and recomputed.
    OPTICAL_INPUT_TOO_LARGE The SVG exceeded the per-file size cap (MAX_INPUT_BYTES). The file was skipped.
    OPTICAL_TIMEOUT The per-file timeout was exceeded. The file was skipped.

    Handling warnings

    Three ways to react to a warning, in increasing order of strictness:

    1. Read the log. Every adapter prints warnings to stderr by default. The code is a stable string so it survives log aggregation and grep.
    2. Hook it. The Vite plugin, PostCSS plugin and programmatic API accept an onWarning callback. Pass null to silence, or route the warning into your logger of choice.
    3. Promote with --strict. The CLI's --strict flag turns warnings into a non-zero exit. CI then fails on, for example, OPTICAL_CLIP_DETECTED before the bad asset ships.