{"id":15650,"library":"image-client-api","title":"Image Client API","description":"The `image-client-api` package, currently at version 1.4060.0, is a specialized JavaScript library developed by Wix for generating highly optimized image URLs. Its core functionality revolves around creating canonical URLs that ensure pixel-perfect image display, minimal download latency, maximum performance, and high quality across a variety of devices and network conditions. It dynamically incorporates advanced features such as optimization for Retina displays, automatic WebP image fetching where supported by the browser, intelligent image sharpening, and machine learning-driven image upscaling. While the versioning (e.g., 1.4060.0) suggests continuous development and a rapid internal release cadence, specific public release cycles or traditional semantic versioning practices are not explicitly detailed, as it primarily serves as an internal Wix library. Its key differentiators are its deep integration with Wix's proprietary image infrastructure, leveraging advanced optimization algorithms and a streamlined API designed for consistent and performant image delivery within the Wix ecosystem.","status":"active","version":"1.4060.0","language":"javascript","source_language":"en","source_url":"https://github.com/wix-private/santa-core","tags":["javascript"],"install":[{"cmd":"npm install image-client-api","lang":"bash","label":"npm"},{"cmd":"yarn add image-client-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add image-client-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily exports a default object in its ES6 module format.","wrong":"import { imageSDK } from 'image-client-api';","symbol":"imageSDK","correct":"import imageSDK from 'image-client-api';"},{"note":"For CommonJS environments, the main export is the default object. The package also provides `dist/cjs/` for CommonJS-only modules if explicit CJS resolution is needed.","wrong":"const { imageSDK } = require('image-client-api');","symbol":"imageSDK","correct":"const imageSDK = require('image-client-api');"},{"note":"When included via a `<script>` tag, the library exposes itself as a global `imageClientSDK` object on the `window`.","symbol":"imageClientSDK","correct":"const imageSDK = window.imageClientSDK;"}],"quickstart":{"code":"import imageSDK from 'image-client-api';\n\n// Create a new Image element to display the optimized image.\nconst img = new Image();\n\n// Use getScaleToFillImageUrl to generate an optimized URL.\n// This example scales 'some-image.jpg' from 1200x800 to fit a 640x480 container,\n// potentially cropping, with a quality setting of 90 and classic upscaling.\nimg.src = imageSDK.getScaleToFillImageUrl(\n  'some-image.jpg', // Relative URL of the image\n  1200,             // Original image width\n  800,              // Original image height\n  640,              // Target container width\n  480,              // Target container height\n  { \n    quality: 90, \n    upscaleMethod: 'classic', \n    name: 'optimized-image' \n  }\n);\n\n// Append the image to the document body to see it (in a browser environment).\ndocument.body.appendChild(img);\n\n// Log the generated URL for inspection.\nconsole.log('Generated Image URL:', img.src);","lang":"javascript","description":"This quickstart demonstrates how to import the `image-client-api` and use `getScaleToFillImageUrl` to generate an optimized image URL for a specified source, target dimensions, and quality settings. It also shows how to apply this URL to an `<img>` tag."},"warnings":[{"fix":"Ensure you are developing within the Wix ecosystem or understand that external usage might not be officially supported or fully functional.","message":"This package is sourced from a private Wix repository and mentions a private npm registry for installation. It is primarily designed for the Wix ecosystem and its functionality might be limited or unsupported outside of that specific environment.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For ES Modules, use `import imageSDK from 'image-client-api';`. For CommonJS, use `const imageSDK = require('image-client-api');`. If loaded via a script tag, access via `window.imageClientSDK`.","message":"The package provides multiple module formats (UMD, CommonJS, ES Modules, Global). Incorrectly importing or referencing the library based on your build system or runtime environment can lead to `undefined` or `not a function` errors. Be mindful of the specific `import`/`require` syntax and the correct export name.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to internal Wix documentation or changelogs for specific version change details, as public semver expectations may not apply.","message":"The version numbering, such as 1.4060.0, suggests an internal or non-standard semantic versioning scheme. This can make it difficult to anticipate breaking changes or track feature updates based on common semver expectations.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Verify your import statement: `import imageSDK from 'image-client-api';` for ESM, `const imageSDK = require('image-client-api');` for CJS, or ensure the global script has loaded before accessing `window.imageClientSDK`.","cause":"The library was not imported correctly in an ES module or CommonJS environment, or the global `imageClientSDK` variable was accessed before the script loaded.","error":"ReferenceError: imageSDK is not defined"},{"fix":"Ensure you are importing the default export: `import imageSDK from 'image-client-api';` or `const imageSDK = require('image-client-api');`. Avoid named imports for the top-level object. Check your bundler configuration if issues persist.","cause":"This usually means `imageSDK` itself was imported, but not as the expected default object, or the object is malformed due to an incorrect module resolution or bundling issue.","error":"TypeError: imageSDK.getScaleToFillImageUrl is not a function"}],"ecosystem":"npm"}