Universal image CDN URL translator
There are many image CDNs that provide a URL API for transforming images. There is little consistency in these APIs, and it's often unclear what the API is for a given URL. This library aims to provide a consistent interface for detecting image CDN URLs and transforming them.
If you'd like to use this on the web, you might want to try Unpic img, a multi-framework image component, powered by Unpic.
It designed to work with image URLs from sources such as CMSs and other user-generated content, where the source image may or may not be from an image CDN, and may already have transforms applied. This allow different transforms to be applied for display on a website. A web framework may need to transform an image for display on a site. Rather than doing this by downloading and resizing it locally or re-processing it with a separate image service, this library can be used to transform the URL to use the original image CDN, which will then transform the image on the fly.
This library is available via URL imports for Deno and via npm for Node. To use it in Deno, import the module from deno.land:
import { transformUrl } from "https://deno.land/x/unpic/mod.ts";
To use it in Node, install it from npm:
npm install unpic
Then import it in your code:
import { transformUrl } from "unpic";
You can then use the transformUrl
function to transform a URL:
const url = transformUrl(
{
url:
"https://cdn.shopify.com/static/sample-images/bath_grande_crop_center.jpeg",
width: 800,
height: 600,
},
);
console.log(url.toString());
// https://cdn.shopify.com/static/sample-images/bath.jpeg?width=800&height=600&crop=center
You can also use the parseUrl
function to parse a URL and get the CDN and any
params:
const parsedUrl = parseUrl(
"https://cdn.shopify.com/static/sample-images/bath_800x600_crop_center.jpeg",
);
console.log(parsedUrl);
// {
// cdn: "shopify",
// width: 800,
// height: 600,
// base: "https://cdn.shopify.com/static/sample-images/bath.jpeg",
// params: {
// crop: "center",
// },
// }
You can bypass auto-detection by specifying the CDN:
const url = transformUrl(
{
url:
"https://cdn.shopify.com/static/sample-images/bath_grande_crop_center.jpeg",
width: 800,
height: 600,
cdn: "shopify",
},
);
This is particularly useful if you are using the CDN with a custom domain which is not auto-detected.
Some transformers support URL delegation. This means that the source image URL
is also checked, and if it matches a CDN then the transform is applied directly
to the source image. For example: consider a next/image
URL that points to an
image on Shopify. The URL is detected as a nextjs
URL because it starts with
/_next/image
. The nextjs
transformer supports delegation, so the source
image URL is then checked. As it matches a Shopify domain, the transform is
applied directly to the Shopify URL. This means that the image is transformed on
the fly by Shopify, rather than by Next.js. However if the source image is not a
supported CDN, or is a local image then the nextjs
transformer will return a
/_next/image
URL.
transformUrl
and parseUrl
.transformUrl
, the library will remove any format set in the
source image, changing it to auto-format. In most cases, this is what you
want. Almost all browsers now support modern formats such as WebP, and setting
auto-format will allow the CDN to serve the best format for the browser. If
you want to force a specific format, you can set it in transformUrl
.transformUrl
, it will return undefined
, as it will for any
URL that is not recognised as an image CDN URL. It is up to you to handle this
case.See the contributing guide.