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 NPM as unpic and JSR as
@unpic/lib.
To use it in Node, install it from npm:
npm install unpic
Then import it in your code:
import { transformUrl } from "unpic";
To use it in Deno, import the module from JSR:
import { transformUrl } from "jsr:@unpic/lib";
If you previously installed the library from deno.land/x, you should update to use JSR instead as the deno.land/x version is no longer updated.
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.
FAQs
Universal image CDN translator
The npm package unpic receives a total of 22,014 weekly downloads. As such, unpic popularity was classified as popular.
We found that unpic demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.