File uploads

Setup#

1. Install

   npm install multer @aws-sdk/client-s3
   npm install sharp            # optional, for image compression

2. Point it at a bucket

   Any S3-compatible storage works. Load these before handling requests — the library reads process.env but never loads .env itself.

   S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
   S3_SPACES_KEY=your-access-key
   S3_SPACES_SECRET=your-secret-key
   S3_BUCKET_NAME=your-bucket
   S3_REGION=us-east-1          # optional, default us-east-1

   Per-provider values (AWS, R2, DigitalOcean, MinIO): Environment variables → S3.

3. Pick where files arrive

   On a CRUD router, add upload (createRouter → S3 uploads). On any other route, use fileUploadMiddleware.

Files on a CRUD router#

For CRUD with files, pass upload to createRouter. The full option list, a complete example and how clients send files are on createRouter → S3 uploads.

app.use('/api/products', createRouter({
  model: Product,
  upload: { fields: [{ name: 'cover', maxCount: 1 }] },
  allowedFields: ['name', 'cover'],          // file fields must be writable
}));

Files on your own routes#

For an avatar endpoint, a file inbox, or anything that isn't CRUD, put fileUploadMiddleware in front of your handler:

import { fileUploadMiddleware } from 'express-controller-sets';

const avatarUpload = (req, res, next) =>
  fileUploadMiddleware(req, res, next, {
    uploadPath: 'avatars/',                  // note: uploadPath here, path on a router
    fields: [{ name: 'avatar', maxCount: 1 }],
    imgOptimizations: 'medium',
    acl: 'public-read',
    allowedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
    maxFileSize: 2 * 1024 * 1024,
  });

app.post('/api/me/avatar', auth.requireAuth, avatarUpload, async (req, res) => {
  await User.updateOne({ _id: req.auth.userId }, { avatar: req.body.avatar });
  res.json({ success: true, data: { avatar: req.body.avatar } });
});

It takes the same options as a router's upload, except the folder is uploadPath instead of path.

What happens to a file#

1. Buffered in memory

   No temp files. maxFileSize and maxFiles apply here.

2. Identified from its bytes

   The file's signature is read; the Content-Type the client sent is ignored. Unrecognised files are a 400.

3. Checked against allowedMimeTypes

   Renaming payload.html to photo.png changes nothing.

4. Optionally compressed

   JPEG, PNG and WebP, if imgOptimizations is set.

5. Uploaded with a safe key

   <path>/<timestamp>-<random>.<ext>, with the extension and Content-Type derived from the final bytes, your ACL, and Content-Disposition: attachment for anything not safe to render inline.

6. URL placed in req.body

   The handler then saves it like any other field.

Image compression#

Set a level and the image is re-encoded toward a target size, binary-searching quality (25–95, at most seven attempts). You get predictable output sizes instead of one fixed quality.

• JPEG, PNG and WebP are re-encoded in the same format. GIF, AVIF and PDF are uploaded as received.
• If sharp is missing or fails, a warning is logged and the original is uploaded.
• To compress a buffer yourself: await compressImage(buffer, 'image/jpeg', 'medium').

When it fails#

S3 configuration is read per request, not at import, so an app that loads its environment after importing the package still works.