If you are building an Express.js application that handles images, whether users are uploading avatars, providing image URLs, or processing local server files, you already know the drill. <\/p>\n\n\n\n
You have to parse the request, buffer the file, send it to an optimization service, wait for the result, and then<\/em> pass it along to your storage logic.<\/p>\n\n\n\n In our previous guide, we covered the core ShortPixel Node SDK<\/a>, which gives you absolute control over this process. <\/p>\n\n\n\n But what if you don’t want to orchestrate all that logic inside every single route handler?<\/p>\n\n\n\n Learn more about Instead of manually wiring up API calls in your controllers, Let’s look at how to set it up and how it handles the three most common image processing scenarios in Express.<\/p>\n\n\n\n The middleware is bundled with the official package. It is ESM-only, so ensure your project has To initialize it, you just need your API key and your preferred optimization settings (like lossy compression or WebP\/AVIF conversion).<\/p>\n\n\n\n Note: The middleware doesn’t parse multipart forms or JSON bodies itself. You still need to mount your standard parsers like The beauty of If you are accepting user uploads via By the time the request hits your controller, Sometimes your users submit a URL instead of a file. The middleware scans the request body for standard whitelisted keys (like If you pass local filesystem paths in the request body (e.g., If you don’t want to attach the middleware to every single image-heavy route, you can mount it globally using the This tells the middleware: “If a request doesn’t contain any image files or matching fields, just skip it and let it proceed normally.”<\/em> Furthermore, the middleware automatically skips uploads and local files smaller than 50KB to save your quota and processing time.<\/p>\n\n\n\nShortPixelExpress<\/code><\/strong> – the official Express middleware layer for the ShortPixel Node SDK.<\/p>\n\n\n\nShortPixelExpress<\/code> acts as a request adapter. You mount it before your route handler, and it automatically intercepts supported images, optimizes them, and hands your route handler a request object populated with fully optimized buffers and normalized metadata.<\/p>\n\n\n\nGetting started<\/h2>\n\n\n\n
\"type\": \"module\"<\/code> in its package.json<\/code> and runs on Node 20 or higher.<\/p>\n\n\n\nnpm i @shortpixel-com\/shortpixel\n<\/code><\/pre>\n\n\n\nimport { ShortPixelExpress } from \"@shortpixel-com\/shortpixel\";\n\nconst optimizeImages = ShortPixelExpress({\n apiKey: process.env.SHORTPIXEL_API_KEY,\n lossy: 1, \/\/ 1 = Lossy compression\n convertto: \"+webp\", \/\/ Automatically generate WebP\n});\n<\/code><\/pre>\n\n\n\nmulter<\/code> or express.json()<\/code> before it.<\/em><\/p>\n\n\n\n3 ways the middleware automates your workflow<\/h2>\n\n\n\n
ShortPixelExpress<\/code> is that it handles the exact input format you throw at it and mutates the request intelligently.<\/p>\n\n\n\n1. Intercepting uploaded files (Multer)<\/h3>\n\n\n\n
multer<\/code>, the middleware reads req.file<\/code> or req.files<\/code>. If the file is in memory, it optimizes it and replaces the buffer in place<\/em>. If it’s on disk, it writes the optimized bytes back to disk and updates the file path.<\/p>\n\n\n\nreq.file.buffer<\/code> is already optimized.<\/p>\n\n\n\nimport express from \"express\";\nimport multer from \"multer\";\nimport { ShortPixelExpress } from \"@shortpixel-com\/shortpixel\";\n\nconst app = express();\nconst upload = multer({ storage: multer.memoryStorage() });\n\napp.post(\n \"\/upload\",\n upload.single(\"image\"),\n ShortPixelExpress({\n apiKey: process.env.SHORTPIXEL_API_KEY,\n lossy: 1,\n convertto: \"+webp\",\n }),\n (req, res) => {\n \/\/ req.file.buffer is ALREADY the optimized WebP buffer!\n const result = req.shortPixel?.files?.[0];\n\n res.json({\n optimizedFilename: req.file?.originalname,\n resultFilename: result?.filename,\n savedToRequest: !!req.file?.buffer,\n });\n }\n);\n<\/code><\/pre>\n\n\n\n2. Processing remote URLs from
req.body<\/code><\/h3>\n\n\n\nurl<\/code> or urls<\/code>). If it finds a valid HTTPS URL, it optimizes the remote image and attaches the result directly to req.shortPixel.urls<\/code>.<\/p>\n\n\n\napp.use(express.json());\n\napp.post(\n \"\/from-url\",\n ShortPixelExpress({\n apiKey: process.env.SHORTPIXEL_API_KEY,\n lossy: 1,\n }),\n (req, res) => {\n \/\/ The original req.body.url is untouched, but the optimized result is ready\n const result = req.shortPixel?.urls?.[0];\n\n res.json({\n sourceUrl: result?.input,\n filename: result?.filename,\n optimizedBytes: result?.buffer?.length,\n });\n }\n);\n<\/code><\/pre>\n\n\n\n3. Optimizing local file paths<\/h3>\n\n\n\n
req.body.imagePath<\/code>), the middleware optimizes the file, writes it next to the original file, and mutates the req.body<\/code> value to point to the new<\/em> optimized path.<\/p>\n\n\n\napp.post(\n \"\/from-path\",\n ShortPixelExpress({\n apiKey: process.env.SHORTPIXEL_API_KEY,\n extraWhitelist: [\"coverPath\"], \/\/ Tell it to look for this specific key\n }),\n (req, res) => {\n const result = req.shortPixel?.paths?.[0];\n\n res.json({\n originalPath: result?.input,\n optimizedPath: req.body.coverPath, \/\/ This has been automatically updated!\n filename: result?.filename,\n });\n }\n);\n<\/code><\/pre>\n\n\n\nGlobal middleware & the
passthrough<\/code> option<\/h2>\n\n\n\npassthrough: true<\/code> option.<\/p>\n\n\n\napp.use(\n ShortPixelExpress({\n apiKey: process.env.SHORTPIXEL_API_KEY,\n passthrough: true, \/\/ Let non-image requests pass through without throwing errors\n lossy: 1,\n })\n);\n<\/code><\/pre>\n\n\n\nSummary<\/h2>\n\n\n\n