Heavy images are one of the most common reasons websites feel sluggish. A product photo that weighs 3MB loads fine on your development machine with a fast connection, but it punishes real users on mobile, and it quietly tanks your Core Web Vitals scores while doing it.<\/p>\n\n\n\n
ShortPixel has been solving this problem for years, and the new Node.js SDK puts that optimization power directly into your backend code. Whether you’re building a content pipeline, processing user uploads, or compressing assets before they hit your CDN, the SDK fits cleanly into existing Node.js workflows.<\/p>\n\n\n\n
This guide walks through the SDK from installation to real-world patterns you can copy straight into a project.<\/p>\n\n\n\n
At its core, the ShortPixel SDK is a wrapper around two API endpoints:<\/p>\n\n\n\n
The SDK handles the transport details: polling, retries, response normalization.<\/p>\n\n\n\n
You pass in an image, configure how you want it processed, and get back download-ready URLs or write files locally.<\/p>\n\n\n\n
The real-world compression numbers can reach up to 86%, which makes a noticeable difference at scale.<\/p>\n\n\n\n
npm i @shortpixel-com\/shortpixel<\/code><\/pre>\n\n\n\nOne thing to be aware of before diving in: the package is ESM-only. Your package.json needs to declare this:<\/p>\n\n\n\n
{\n \"type\": \"module\"\n}<\/code><\/pre>\n\n\n\nNode 20+ is recommended. The SDK won’t work reliably in CommonJS environments without additional configuration.<\/p>\n\n\n\n
Setting up the client<\/h2>\n\n\n\n
Every operation flows through a ShortPixelClient instance. You’ll need an API key from shortpixel.com to get started.<\/p>\n\n\n\n
import SHORTPIXEL from \"@shortpixel-com\/shortpixel\";\n\nconst { ShortPixelClient } = SHORTPIXEL;\n\nconst cli = new ShortPixelClient({\n apiKey: process.env.SHORTPIXEL_API_KEY,\n});<\/code><\/pre>\n\n\n\nStore your API key in an environment variable, never hardcode it. A .env file with a library like dotenv works fine here.<\/p>\n\n\n\n
Four ways to think about the API<\/h2>\n\n\n\n
The SDK is designed with multiple layers of abstraction, and which one you reach for depends on how much control you need.<\/p>\n\n\n\n
\n- Explicit helpers:<\/strong>
fromFile<\/code>, fromUrl<\/code>, fromBuffer<\/code>. These map directly to an endpoint and make it obvious what’s happening. Good for large codebases where clarity matters.<\/li>\n\n\n\n- Intent-first aliases:<\/strong>
optimizeFile<\/code>, optimizeUrl<\/code>, optimizeBuffer<\/code>. Same behavior, naming that reads more naturally.<\/li>\n\n\n\n- Generic dispatcher:<\/strong>
optimize(input)<\/code>. Pass in a file path, URL, or Buffer, and the SDK routes it automatically. Cleanest for quick scripts.<\/li>\n\n\n\n- Feature helpers:<\/strong>
upscale<\/code>, rescale<\/code>, backgroundRemove<\/code>, convert<\/code>. These set intelligent defaults for specific operations and still accept any additional options you need.<\/li>\n<\/ol>\n\n\n\nIn practice, you’ll likely mix these. Feature helpers are great for readability; explicit helpers are better when your team needs to trace exactly what’s hitting which endpoint.<\/p>\n\n\n\n
Basic file optimization<\/h2>\n\n\n\n
The simplest case: take a local image, compress it, and write the result to a folder.<\/p>\n\n\n\n
const src = await cli.fromFile(\"assets\/product-shot.png\", { lossy: 1 });\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nThe lossy<\/code> parameter controls compression aggressiveness:<\/p>\n\n\n\n\n0<\/code> \u2014 lossless (no quality reduction)<\/li>\n\n\n\n1<\/code> \u2014 lossy (good balance of size and quality)<\/li>\n\n\n\n2<\/code> \u2014 glossy (more aggressive, still visually acceptable for most use cases)<\/li>\n<\/ul>\n\n\n\nIf you prefer named methods:<\/p>\n\n\n\n
const src = await cli.glossy(\"assets\/product-shot.png\");\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nOptimizing remote URLs<\/h2>\n\n\n\n
For images that live on a CDN or external server, pass the URL directly:<\/p>\n\n\n\n
const src = await cli.fromUrl(\n \"https:\/\/example.com\/images\/hero-banner.jpg\",\n { lossy: 1, convertto: \"+webp\" }\n);\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nThe convertto: \"+webp\"<\/code> option tells ShortPixel to produce the optimized original plus a WebP version. If you only want WebP (no original), use \"webp\"<\/code> without the +<\/code>.<\/p>\n\n\n\nFormat conversion<\/h2>\n\n\n\n
Modern image formats like WebP and AVIF deliver significantly better compression than JPEG or PNG at equivalent quality. The convertto<\/code> option handles this:<\/p>\n\n\n\n\/\/ Original + WebP\nawait cli.convert(\"assets\/banner.jpg\", \"+webp\");\n\n\/\/ Only WebP and AVIF, no original\nawait cli.convert(\"assets\/banner.jpg\", \"webp|avif\");\n\n\/\/ Original + WebP + AVIF\nawait cli.convert(\"assets\/banner.jpg\", \"+webp|+avif\");<\/code><\/pre>\n\n\n\nThe +<\/code> prefix means “keep the optimized original as well.” Without it, only the converted formats are returned.<\/p>\n\n\n\nResizing and upscaling<\/h2>\n\n\n\n
The SDK exposes several resize modes that correspond to different visual outcomes.<\/p>\n\n\n\n
Upscaling<\/strong> \u2014 useful when you need to increase an image’s resolution without losing detail:<\/p>\n\n\n\nconst src = await cli.upscale(\"assets\/thumbnail.png\", 2, {\n lossy: 0,\n convertto: \"+webp\",\n});\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nThe second argument is the upscale factor (2x, 3x, or 4x). Valid values are 2<\/code>, 3<\/code>, and 4<\/code>.<\/p>\n\n\n\nRescale (outer)<\/strong> \u2014 resize to fit within given dimensions, maintaining aspect ratio:<\/p>\n\n\n\nconst src = await cli.rescale(\"assets\/photo.jpg\", 1200, 800, {\n convertto: \"+avif\",\n});\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nResize inner<\/strong> \u2014 resize so the image fills the dimensions, potentially cropping:<\/p>\n\n\n\nconst src = await cli.resizeInner(\"assets\/product.jpg\", 600, 600);\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nSmart crop<\/strong> \u2014 like inner resize, but uses AI to focus on the most important part of the image:<\/p>\n\n\n\nconst src = await cli.smartCrop(\"assets\/portrait.jpg\", 400, 400, {\n convertto: \"+webp\",\n});\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nSmart crop is particularly useful for product images or portraits where you don’t want to lose the subject when cropping to a square.<\/p>\n\n\n\n
Background removal and replacement<\/h2>\n\n\n\n
ShortPixel can remove image backgrounds or replace them with a color or another image.<\/p>\n\n\n\n
Remove the background (returns transparent PNG):<\/p>\n\n\n\n
const src = await cli.backgroundRemove(\"assets\/product.png\", {\n convertto: \"+webp\",\n});\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nReplace with a solid color using an #rrggbbaa<\/code> hex value (the last two characters control opacity):<\/p>\n\n\n\n\/\/ Warning: background operations take longer to process\nconst src = await cli.backgroundChange(\"assets\/product.png\", \"#ffffff00\", {\n lossy: 2,\n});\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nReplace with another image:<\/p>\n\n\n\n
const src = await cli.backgroundChange(\n \"assets\/product.png\",\n \"https:\/\/example.com\/studio-background.jpg\",\n { convertto: \"+webp\" }\n);\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nBackground operations are more computationally intensive than basic compression, so expect longer processing times. You may need to increase the polling configuration (more on that below).<\/p>\n\n\n\n
Processing multiple files<\/h2>\n\n\n\n
The SDK handles batches cleanly. You can pass arrays to any of the batch methods.<\/p>\n\n\n\n
Multiple local files:<\/p>\n\n\n\n
const src = await cli.fromFiles([\n \"assets\/product-1.jpg\",\n \"assets\/product-2.jpg\",\n \"assets\/product-3.jpg\",\n], {\n lossy: 1,\n convertto: \"+webp\",\n});\n\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nMultiple URLs:<\/p>\n\n\n\n
const src = await cli.fromUrls([\n \"https:\/\/example.com\/images\/image-1.jpg\",\n \"https:\/\/example.com\/images\/image-2.jpg\",\n], {\n lossy: 2,\n convertto: \"+avif\",\n});\n\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nOne important restriction: don’t mix local file paths and remote URLs in the same array. The SDK will throw an error because they route to different endpoints.<\/p>\n\n\n\n
Working with buffers<\/h2>\n\n\n\n
When you’re handling file uploads in a web server and want to process images before saving them, buffers are the right approach:<\/p>\n\n\n\n
import fs from \"fs\";\n\nconst imageBuffer = fs.readFileSync(\"assets\/upload.png\");\n\nconst src = await cli.fromBuffer(imageBuffer, \"upload.png\", {\n lossy: 1,\n convertto: \"+webp\",\n});\n\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nFor multiple buffers:<\/p>\n\n\n\n
const src = await cli.fromBuffers([\n { buffer: bufferA, filename: \"image-a.png\" },\n { buffer: bufferB, filename: \"image-b.png\" },\n], \"fallback.png\", { lossy: 1 });\n\nawait src.downloadTo(\".\/output\");<\/code><\/pre>\n\n\n\nConfiguring polling and retries<\/h2>\n\n\n\n
ShortPixel’s API is asynchronous \u2014 you submit an image and poll for the result. The SDK handles this automatically, but the defaults may need adjusting for complex operations like background removal or AI-based upscaling.<\/p>\n\n\n\n
\/\/ Increase timeout for long-running operations\ncli.set(\"timeout\", 60000);\n\n\/\/ More retries on temporary failures\ncli.set(\"retries\", 5);\ncli.set(\"retryDelay\", 1500);\n\n\/\/ Tune polling for complex operations\ncli.set(\"poll\", {\n enabled: true,\n interval: 3000, \/\/ check every 3 seconds\n maxAttempts: 30, \/\/ try up to 30 times\n});<\/code><\/pre>\n\n\n\nIf you’re running background removal jobs and getting timeout errors, increasing interval<\/code> and maxAttempts<\/code> is usually the fix.<\/p>\n\n\n\nYou can also set a global default output format so you don’t have to repeat it on every call:<\/p>\n\n\n\n
cli.set(\"convertto\", \"+webp\");<\/code><\/pre>\n\n\n\nInspecting metadata<\/h2>\n\n\n\n
Every Source object returned by an operation includes lastMetas<\/code> \u2014 the raw API response for each processed item. This is useful for debugging or when you need to handle output URLs yourself:<\/p>\n\n\n\nconst src = await cli.fromFile(\"assets\/image.png\", {\n lossy: 1,\n convertto: \"+webp|+avif\",\n});\n\nfor (const meta of src.lastMetas || []) {\n console.log(\"Status code:\", Number(meta?.Status?.Code));\n console.log(\"Status message:\", meta?.Status?.Message);\n console.log(\"Optimized URL:\", meta?.LossyURL);\n console.log(\"WebP URL:\", meta?.WebPLossyURL || meta?.WebPLosslessURL);\n console.log(\"AVIF URL:\", meta?.AVIFLossyURL || meta?.AVIFLosslessURL);\n}<\/code><\/pre>\n\n\n\nStatus code 2<\/code> means the image was processed successfully. Status code 1<\/code> means it’s still pending (the SDK handles polling automatically, so you shouldn’t see this often in normal operation).<\/p>\n\n\n\nError handling<\/h2>\n\n\n\n
The SDK uses typed errors, which makes it straightforward to handle specific failure modes:<\/p>\n\n\n\n
try {\n const src = await cli.fromFile(\"assets\/image.png\", { upscale: 4 });\n await src.downloadTo(\".\/output\");\n} catch (err) {\n if (err.name === \"ShortPixelAuthError\") {\n console.error(\"Invalid API key\");\n } else if (err.name === \"ShortPixelQuotaError\") {\n console.error(\"Monthly quota exceeded\");\n } else if (err.name === \"ShortPixelTemporaryError\") {\n console.error(\"Temporary API issue, retry later\");\n } else if (err.name === \"ShortPixelInvalidRequestError\") {\n console.error(\"Invalid request parameters\");\n } else {\n console.error(\"Unexpected error:\", err.name);\n console.error(\"SP code:\", err.spCode);\n console.error(\"Message:\", err.spMessage);\n }\n}<\/code><\/pre>\n\n\n\nThe full set of typed errors the SDK can throw is: ShortPixelError<\/code> (base class), ShortPixelAuthError<\/code>, ShortPixelQuotaError<\/code>, ShortPixelTemporaryError<\/code>, ShortPixelInvalidRequestError<\/code>, and ShortPixelBatchError<\/code>.<\/p>\n\n\n\nIn batch mode, if one or more items fail, the SDK throws a ShortPixelBatchError<\/code> that includes per-item error details. You can iterate through those to handle partial failures gracefully.<\/p>\n\n\n\nExample: Image pipeline for user uploads<\/h2>\n\n\n\n
Here’s a pattern you might use in a Node.js API route that processes user-uploaded images:<\/p>\n\n\n\n
import SHORTPIXEL from \"@shortpixel-com\/shortpixel\";\nimport fs from \"fs\";\nimport path from \"path\";\n\nconst { ShortPixelClient } = SHORTPIXEL;\n\nconst cli = new ShortPixelClient({\n apiKey: process.env.SHORTPIXEL_API_KEY,\n});\n\n\/\/ Set global defaults once\ncli.set(\"convertto\", \"+webp\");\ncli.set(\"poll\", { enabled: true, interval: 2000, maxAttempts: 25 });\n\nasync function processUserUpload(uploadedBuffer, originalFilename) {\n try {\n const src = await cli.fromBuffer(uploadedBuffer, originalFilename, {\n lossy: 1,\n keep_exif: 0,\n });\n\n const outputDir = path.join(\".\/storage\", \"optimized\");\n fs.mkdirSync(outputDir, { recursive: true });\n\n const files = await src.downloadTo(outputDir);\n\n return {\n success: true,\n files,\n };\n } catch (err) {\n console.error(\"Optimization failed:\", err.name, err.spMessage);\n return {\n success: false,\n error: err.name,\n };\n }\n}<\/code><\/pre>\n\n\n\nA few things to keep in mind<\/h2>\n\n\n\n
HTTPS is enforced throughout the SDK. Any input URL using plain http:\/\/<\/code> will be rejected before a network call is made.<\/p>\n\n\n\nOutput URLs that come back over HTTP from the API are automatically upgraded to HTTPS. This is the expected behavior and not something you need to work around.<\/p>\n\n\n\n
The pluginVersion<\/code> constructor option must be five characters or fewer. It’s optional, but if you pass something longer, initialization will fail.<\/p>\n\n\n\ndownloadTo()<\/code> only works after an optimization call completes. Calling it on a freshly instantiated Source without running a job first won’t do anything useful. useful.<\/p>\n\n\n\n\nResources<\/strong><\/p>\n\n\n\n\ud83d\udcc4 ShortPixel SDK<\/a><\/strong>
\ud83d\udcc4 API documentation<\/a><\/strong><\/p>\n<\/div>\n","protected":false},"excerpt":{"rendered":"Heavy images are one of the most common reasons websites feel sluggish. A product photo that weighs 3MB loads fine on your development machine with a fast connection, but it punishes real users on mobile, and it quietly tanks your Core Web Vitals scores while doing it. ShortPixel has been solving this problem for years, […]<\/p>\n","protected":false},"author":22,"featured_media":14496,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-14494","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-world-of-wordpress"],"blocksy_meta":[],"_links":{"self":[{"href":"https:\/\/shortpixel.com\/blog\/wp-json\/wp\/v2\/posts\/14494","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/shortpixel.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/shortpixel.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/shortpixel.com\/blog\/wp-json\/wp\/v2\/users\/22"}],"replies":[{"embeddable":true,"href":"https:\/\/shortpixel.com\/blog\/wp-json\/wp\/v2\/comments?post=14494"}],"version-history":[{"count":18,"href":"https:\/\/shortpixel.com\/blog\/wp-json\/wp\/v2\/posts\/14494\/revisions"}],"predecessor-version":[{"id":14584,"href":"https:\/\/shortpixel.com\/blog\/wp-json\/wp\/v2\/posts\/14494\/revisions\/14584"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/shortpixel.com\/blog\/wp-json\/wp\/v2\/media\/14496"}],"wp:attachment":[{"href":"https:\/\/shortpixel.com\/blog\/wp-json\/wp\/v2\/media?parent=14494"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/shortpixel.com\/blog\/wp-json\/wp\/v2\/categories?post=14494"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/shortpixel.com\/blog\/wp-json\/wp\/v2\/tags?post=14494"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}