Product image processing with Sharp and Google Cloud

Every product in the store has up to four purpose-built image variants — a full-size principal photo, a thumbnail, a high-resolution zoom, and a square catalog crop. Rather than serving one large original everywhere, the API generates all four sizes at upload time using Sharp, converts them to space-efficient WebP at quality 70, and stores the results in Google Cloud Storage. MongoDB only ever holds the resulting public URLs, keeping your database lean and your images edge-cached.

Upload pipeline

Client sends multipart/form-data

The client submits a POST request with product fields and image files as a multipart/form-data body. Each image is sent under one of four named fields (see Multer fields below).

Multer saves files locally

The multer middleware intercepts the upload and writes each file to storage/product/ on the server’s local filesystem. Files are held here temporarily while processing occurs.

imageGenerate runs Sharp

The imageGenerate function in src/middleware/tools/process.js reads each locally saved file and uses Sharp to produce four resized WebP variants — one per image role. All variants are generated from the same source file in a single pass.

Variants uploaded to Google Cloud Storage

Each processed buffer is uploaded to the GCS bucket named by the NAMEGOOGLECLOUD environment variable. The destination filename follows the pattern {datename}{suffix}_{baseName}.webp, where datename is a date-derived string prefix and suffix is one of ip, mn, idz, or ic.

Local file deleted

Once all four GCS uploads succeed, the temporary local file in storage/product/ is removed to keep disk usage in check.

Image object written to MongoDB

The imageGenerate function returns a structured image object containing all four public GCS URLs. This object is pushed into the appropriate image array on the Product document (e.g., imageUrlIp, imageUrlMn, etc.).

The four image variants

Each uploaded image produces four independently sized outputs. All outputs are WebP at quality 70, regardless of the source format.

Variant	Product field	Dimensions	Aspect ratio	Intended use
`ip` — Principal	`imageUrlIp`	1500 × 2000 px	3:4	Primary product photo on listing and detail pages
`mn` — Thumbnail	`imageUrlMn`	500 × 666 px	3:4	Search results, carousels, compact grids
`idz` — Detail/zoom	`imageUrlIdz`	2000 × 2667 px	3:4	High-resolution zoom viewer on the product detail page
`ic` — Square catalog	`imageUrlIc`	1080 × 1080 px	1:1	Square catalog grids and social-media sharing cards

Sharp’s .resize() is called with { fit: 'cover' } semantics, so the source image is cropped to fill the target canvas exactly. Ensure your source photos are at least 2000 px on their shortest side to avoid upscaling artefacts.

Multer upload fields

Product create and update endpoints accept exactly four named file fields via multer. Send each image under its corresponding field name.

Field name	Image role	Description
`imageUrlIp`	Principal	Main portrait photo, 3:4
`imageUrlMn`	Thumbnail	Small portrait, 3:4
`imageUrlIdz`	Detail/zoom	Large portrait for zoom, 3:4
`imageUrlIc`	Square catalog	Square crop, 1:1

Upload all four angles of the shirt for the best shopping experience — for example: front, back, detail shot, and a styled flat-lay for the square catalog image. Using the same photo for all four fields is valid but reduces the quality of zoom and catalog views.

Image format and quality

All variants are always written as WebP regardless of the source image format (JPEG, PNG, etc.). The WebP encoder is called with quality: 70, which strikes a balance between file size and visual fidelity suitable for e-commerce product photography.

Setting	Value
Output format	WebP
Quality	70
Source formats accepted	Any format supported by Sharp (JPEG, PNG, TIFF, GIF, …)

GCS URL pattern

Every uploaded variant gets a unique public URL in this form:

https://storage.googleapis.com/{BUCKET_NAME}/{datename}{suffix}_{baseName}.webp

For example:

https://storage.googleapis.com/my-shirt-store/20240628120000-00000classic-oxford.webp

The timestamp prefix is a date-derived string assembled from the current year, day, month, hours, minutes, a hyphen, seconds, and milliseconds — appended immediately before the processed filename. This guarantees uniqueness and prevents stale CDN caches from serving an old image when a product photo is replaced.

Image object structure in MongoDB

After processing, imageGenerate returns one object per processed image. That object is stored inside the product’s image array fields:

{
  "_id": "64f3a1b2c8e4d90012345678",
  "urlip":   "https://storage.googleapis.com/my-shirt-store/20240628120000-00000front.webp",
  "urlmn":   "https://storage.googleapis.com/my-shirt-store/20240628120000-00000front_mn.webp",
  "urlidz":  "https://storage.googleapis.com/my-shirt-store/20240628120000-00000front_idz.webp",
  "urlic":   "https://storage.googleapis.com/my-shirt-store/20240628120000-00000front_ic.webp",
  "imageUrlIp": "https://storage.googleapis.com/my-shirt-store/20240628120000-00000front.webp"
}

_id

string

Unique identifier for this image object, generated by MongoDB.

urlip

string

Public GCS URL for the principal image (1500×2000 px WebP).

urlmn

string

Public GCS URL for the thumbnail image (500×666 px WebP).

urlidz

string

Public GCS URL for the detail/zoom image (2000×2667 px WebP).

urlic

string

Public GCS URL for the square catalog image (1080×1080 px WebP).

[fieldName]

string

The public GCS URL of the principal (ip) variant, keyed by the multer field name (e.g., imageUrlIp). Mirrors the value of urlip and is used internally to trace which upload slot produced this object.

Environment variables

The GCS bucket name is read from the NAMEGOOGLECLOUD environment variable at runtime. Make sure this variable is set in your .env file (or your deployment environment) before starting the server — missing it will cause all image uploads to fail.

# .env
NAMEGOOGLECLOUD=my-shirt-store-bucket

Example: creating a product with images

The following curl command creates a new product and uploads all four image variants in a single multipart request.

curl -X POST https://api.example.com/api/product/create \
  -H "Authorization: Bearer <TOKEN>" \
  -F "title=Classic Oxford Button-Down" \
  -F "description=A timeless Oxford shirt in 100% cotton." \
  -F "sizes[]=S" \
  -F "sizes[]=M" \
  -F "sizes[]=L" \
  -F "price=75000" \
  -F "discount=Sin descuento" \
  -F "discountPrice=" \
  -F "minCant=30" \
  -F "imageUrlIp=@./photos/oxford-front.jpg;type=image/jpeg" \
  -F "imageUrlMn=@./photos/oxford-front.jpg;type=image/jpeg" \
  -F "imageUrlIdz=@./photos/oxford-front-hires.jpg;type=image/jpeg" \
  -F "imageUrlIc=@./photos/oxford-square.jpg;type=image/jpeg"

A successful response will include the new product document with all four imageUrl* arrays populated with GCS objects:

{
  "status": 200,
  "product": {
    "_id": "64f3a1b2c8e4d90012345678",
    "title": "Classic Oxford Button-Down",
    "price": 75000,
    "imageUrlIp":  [{ "_id": "...", "urlip": "https://storage.googleapis.com/...", "urlmn": "...", "urlidz": "...", "urlic": "..." }],
    "imageUrlMn":  [{ "_id": "...", "urlip": "https://storage.googleapis.com/...", "..." }],
    "imageUrlIdz": [{ "_id": "...", "urlip": "https://storage.googleapis.com/...", "..." }],
    "imageUrlIc":  [{ "_id": "...", "urlip": "https://storage.googleapis.com/...", "..." }],
    "minCant": 30,
    "createdAt": "2024-06-28T12:00:00.000Z",
    "updatedAt": "2024-06-28T12:00:00.000Z"
  }
}

You can reuse the same source file for multiple fields (as shown above for imageUrlIp and imageUrlMn), but Sharp will still generate all four resize variants from that file independently. For best results, provide distinct, properly composed photos for each slot.

Getting Started

Authentication

Core Concepts

Product image processing with Sharp and Google Cloud

Upload pipeline

The four image variants

Multer upload fields

Image format and quality

GCS URL pattern

Image object structure in MongoDB

Environment variables

Example: creating a product with images

Build docs developers (and LLMs) love

Getting Started

Authentication

Core Concepts

Documentation Index

​Upload pipeline

​The four image variants

​Multer upload fields

​Image format and quality

​GCS URL pattern

​Image object structure in MongoDB

​Environment variables

​Example: creating a product with images

Build docs developers (and LLMs) love

Upload pipeline

The four image variants

Multer upload fields

Image format and quality

GCS URL pattern

Image object structure in MongoDB

Environment variables

Example: creating a product with images