Image Client API

1.4060.0 · active · verified Tue Apr 21

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.

Common errors

```
ReferenceError: imageSDK is not defined
```
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.

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`.
```
TypeError: imageSDK.getScaleToFillImageUrl is not a function
```
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.

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.

Warnings

gotcha 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.
Fix: Ensure you are developing within the Wix ecosystem or understand that external usage might not be officially supported or fully functional.
gotcha 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.
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`.
gotcha 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.
Fix: Refer to internal Wix documentation or changelogs for specific version change details, as public semver expectations may not apply.

Install

npm install image-client-api npm
yarn add image-client-api yarn
pnpm add image-client-api pnpm

Imports

imageSDK
wrong:
```
import { imageSDK } from 'image-client-api';
```
correct:
```
import imageSDK from 'image-client-api';
```
The library primarily exports a default object in its ES6 module format.
imageSDK
wrong:
```
const { imageSDK } = require('image-client-api');
```
correct:
```
const imageSDK = require('image-client-api');
```
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.
imageClientSDK
```
const imageSDK = window.imageClientSDK;
```
When included via a `<script>` tag, the library exposes itself as a global `imageClientSDK` object on the `window`.

Quickstart

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.

import imageSDK from 'image-client-api';

// Create a new Image element to display the optimized image.
const img = new Image();

// Use getScaleToFillImageUrl to generate an optimized URL.
// This example scales 'some-image.jpg' from 1200x800 to fit a 640x480 container,
// potentially cropping, with a quality setting of 90 and classic upscaling.
img.src = imageSDK.getScaleToFillImageUrl(
  'some-image.jpg', // Relative URL of the image
  1200,             // Original image width
  800,              // Original image height
  640,              // Target container width
  480,              // Target container height
  { 
    quality: 90, 
    upscaleMethod: 'classic', 
    name: 'optimized-image' 
  }
);

// Append the image to the document body to see it (in a browser environment).
document.body.appendChild(img);

// Log the generated URL for inspection.
console.log('Generated Image URL:', img.src);

view raw JSON →