How to reliably process images in your Express application

Processing images directly from your Express endpoints comes with many downsides:

Impact on your overall API performance

sharp, while being efficient, is performing CPU-intensive operations that, by running on the same servers as your API web processes, will impact the overall performance of your API (ex: lowering RPS).

Does the API consumer need to get the result?

The sole duty of an API is to get requests that perform actions and may return an associated result. For image processing use cases, does the consumer needs the result? If not, why wait for the image processing to be performed before responding?

Memory leaks issues

Web processes running your API usually run for a long time, only rebooted on new deployments on your application. sharp memory leak issues are again resurfacing, as reported by many users.

Moving the image processing in the background (e.g., queues) is the best practice to ensure the reliability of your Express application.

Let's see an example that generates thumbnail variation during a new user onboarding flow.

Reliably create avatar thumbnails variation

Consider the following flow:

1. The user uploads an avatar that is uploaded to S3 from the front-end
2. Users submit their account details to POST /user along with the S3 file key as avatar
3. The express POST /user endpoint:
   1. creates the user record with the proper avatar, and defaults thumbnails_* values
   2. Enqueue a background job to create the thumbnail variations without impacting the overall API performances
4. The background job:
   1. creates the thumbnail variations using sharp: small, medium, and large rounded versions of the original avatar
   2. upload them on S3
   3. and updates the user record

Let's see how to implement it step-by-step.

1. The POST /user endpoint

Our POST /account endpoint creates a new account and sets default values for the thumbnails:

1import express from "express"2
3import prisma from "./prismaClient"4
5const app = express()6app.use(express.json())7
8const port = 30009
10app.post("/user", async (req, res) => {11  const data = req.body12  const user = await prisma.user.create({13    data: {14      ...data,15      avatar: data.fileName,16      // Put placeholder values17      thumbnailSmall: fileName,18      thumbnailMedium: fileName,19      thumbnailLarge: fileName,20    },21  })22
23  // TODO: create the thumbnail variations24  //       in the background25
26  res.json({ user })27})28
29app.listen(port, () => {30  console.log(`Example app listening on port ${port}`)31})32

Let's now implement the thumbnail variations generation with sharp.

2. Implementing the image processing logic

Let's create a createThumbnail() function that will take the following image:

A creates 3 different sizes rounded versions (100x100, 200x200, 400x400):

Creating rounded thumbnails with sharp

A rounded PNG version of an image is achieved by using the .composite() API from sharp with an SVG circle, used as a mask (blend: "dest-in"):

1import sharp from "sharp"2import {3  S3Client,4  GetObjectCommand,5  PutObjectCommand,6} from "@aws-sdk/client-s3"7
8import s3Config from "../s3Config"9
10const s3Client = new S3Client(s3Config)11
12const rect = (w: number, h: number) =>13  Buffer.from(14    `<svg>15      <rect16        x="0"17        y="0"18        width="${w}"19        height="${h}"20        rx="${w}"21        ry="${h}"22      />23    </svg>`24  )25
26const sizes = {27  small: [100, 100],28  medium: [200, 200],29  large: [400, 400],30} as const31
32async function createThumbnail(33  fileName: string,34  imageSource: Uint8Array,35  size: keyof typeof sizes36) {37  const dimensions = sizes[size]38  const thumbnailFile = `${fileName}_${size}`39  const thumbnailSource = await sharp(imageSource)40    .resize(...dimensions)41    .composite([42      {43        input: rect(dimensions[0], dimensions[1]),44        blend: "dest-in",45      },46    ])47    .png()48    .toBuffer()49  const bucketParams = {50    Bucket: process.env.AWS_S3_BUCKET_NAME,51    Key: fileName,52    Body: thumbnailSource,53  }54  await s3Client.send(new PutObjectCommand(bucketParams))55  return thumbnailFile56}57

Let's now call our createThumbnail() function from a background function that will generate all the thumbnail variations from the original uploaded avatar.

Implementing the background function — using Defer

Let's create a background function that will run in the background - on Defer upon call.

For this, we create a src/defer/createThumbnails.ts file as follows:

1import { defer } from "@defer/client"2import {3  S3Client,4  GetObjectCommand,5  PutObjectCommand,6} from "@aws-sdk/client-s3"7
8import prisma from "../prismaClient"9import s3Config from "../s3Config"10import createThumbnail from "../createThumbnail"11
12const s3Client = new S3Client(s3Config)13
14//15async function createThumbnails(accountId: string) {16  const { avatar } = await prisma.user.findUnique({17    where: {18      id: accountId,19    },20  })21
22  const bucketParams = {23    Bucket: process.env.AWS_S3_BUCKET_NAME,24    Key: avatar,25  }26  const { Body } = await s3Client.send(new GetObjectCommand(bucketParams))27  const source = await Body?.transformToByteArray()28  if (!source) {29    throw new Error("could not parse image source")30  }31
32  const [thumbnailSmall, thumbnailMedium, thumbnailLarge] =33    await Promise.all([34      createThumbnail(avatar, source, "small"),35      createThumbnail(avatar, source, "medium"),36      createThumbnail(avatar, source, "large"),37    ])38
39  await prisma.user.update({40    where: {41      id: accountId,42    },43    data: {44      thumbnailSmall,45      thumbnailMedium,46      thumbnailLarge,47    },48  })49}50
51export default defer(createThumbnails, {52  // Retry in case of AWS or database issues53  retry: 5,54})55

Let's now see how to trigger a createThumbnails() execution from our POST /user endpoint.

3. Triggering a background function run

Let's import createThumbnails() from defer/createThumbnails and simply call the background function with the newly created user.id.

src/server.ts

1// [...]2import createThumbnails from "../defer/createThumbnails"3
4app.post("/user", async (req, res) => {5  const user = await prisma.user.create({6    data: {7      // ...8      avatar: fileName,9      // put placeholder values10      thumbnailSmall: fileName,11      thumbnailMedium: fileName,12      thumbnailLarge: fileName,13    },14  })15
16  // this call with offload the function17  //  execution on the Defer Platform18  await createThumbnails(user.id)19
20  res.json({ user })21})22
23// [...]24

Going further

Moving the image processing outside of the API lifecycle is one example of how to build resilient and performant Express APIs.

Other use cases to explore are:

• Generating reports or export of data
• Interacting with third-party APIs (ex: Stripe)
• Sending and receiving webhooks