File Uploads

Accepting files from clients - multer middleware, handling multipart form data, file validation, and storing uploads locally or in cloud storage.

What it is, in plain English: File uploads use a special request encoding called multipart/form-data, which express.json() cannot parse -- it's designed for binary file content, not JSON. Multer is the standard Express middleware for handling multipart uploads: it parses the incoming file data, makes it available on req.file (single) or req.files (multiple), and can validate file type/size before your route handler ever runs.

Why express.json() can't handle file uploads

File uploads use a different request format called multipart/form-data -- it can mix text fields and binary file content in one request. express.json() only understands JSON text, so a separate middleware is needed: multer.

Basic setup -- a single file upload

# npm install multer

import multer from "multer";

const upload = multer({ dest: "uploads/" });   // saves files to an "uploads" folder

app.post("/upload", upload.single("avatar"), (req, res) => {
  // "avatar" must match the form field name the client used
  console.log(req.file);
  // { fieldname: "avatar", originalname: "photo.jpg", mimetype: "image/jpeg",
  //   path: "uploads/a1b2c3...", size: 204800 }

  res.json({
    filename: req.file.filename,
    size:     req.file.size,
  });
});

<!-- The HTML form a client would submit from: -->
<form action="/upload" method="POST" enctype="multipart/form-data">
  <input type="file" name="avatar" />
  <button type="submit">Upload</button>
</form>
<!-- enctype="multipart/form-data" is REQUIRED for file uploads -->

Multiple files

// Multiple files under the SAME field name:
app.post("/gallery", upload.array("photos", 10), (req, res) => {
  // req.files is an ARRAY (not req.file) when using .array()
  res.json({ uploaded: req.files.length });
});

// Multiple DIFFERENT field names:
app.post("/profile", upload.fields([
  { name: "avatar", maxCount: 1 },
  { name: "coverPhoto", maxCount: 1 },
]), (req, res) => {
  // req.files.avatar[0], req.files.coverPhoto[0]
  res.json({ avatar: req.files.avatar[0].filename });
});

Restricting file types and size

const upload = multer({
  dest: "uploads/",
  limits: { fileSize: 5 * 1024 * 1024 },   // 5MB max
  fileFilter: (req, file, cb) => {
    const allowed = ["image/jpeg", "image/png", "image/webp"];
    if (!allowed.includes(file.mimetype)) {
      return cb(new Error("Only JPEG, PNG, and WebP images allowed"));
    }
    cb(null, true);   // accept the file
  },
});

Try It Yourself (Node.js logic)

// File uploads with multer -- the standard Express pattern
// (multer needs npm install multer + a real multipart request -- reference code shown)

const MULTER_BASIC = `
import multer from "multer";

// Store uploaded files on disk in an "uploads" folder:
const upload = multer({ dest: "uploads/" });

app.post("/upload", upload.single("avatar"), (req, res) => {
  // req.file contains info about the uploaded file:
  console.log(req.file);
  // {
  //   fieldname: "avatar",
  //   originalname: "photo.jpg",
  //   mimetype: "image/jpeg",
  //   path: "uploads/a1b2c3d4",
  //   size: 204800
  // }
  res.json({ filename: req.file.filename, size: req.file.size });
});

// Multiple files at once:
app.post("/gallery", upload.array("photos", 10), (req, res) => {
  // req.files is an ARRAY when using .array()
  res.json({ count: req.files.length });
});
`;

console.log("Basic multer setup:");
console.log(MULTER_BASIC.trim());

// File validation logic (the kind multer's fileFilter uses) -- runs here:
function validateFile(file) {
  const allowedTypes = ["image/jpeg", "image/png", "image/webp"];
  const maxSize = 5 * 1024 * 1024;  // 5 MB

console.log("\nValidating a 2MB JPEG:");
console.log(validateFile({ mimetype: "image/jpeg", size: 2 * 1024 * 1024 }));

console.log("\nValidating a 10MB PDF:");
console.log(validateFile({ mimetype: "application/pdf", size: 10 * 1024 * 1024 }));

Memory storage, custom filenames, and error handling

Disk storage vs memory storage

// Disk storage (what we've used) -- writes directly to disk:
const diskUpload = multer({ dest: "uploads/" });

// Memory storage -- keeps the file as a Buffer in memory (req.file.buffer):
// Useful when you're about to upload it elsewhere (S3, Cloudinary)
// and don't need a local copy:
const memoryUpload = multer({ storage: multer.memoryStorage() });

app.post("/upload", memoryUpload.single("photo"), async (req, res) => {
  // req.file.buffer is the raw file bytes -- never touched disk
  await uploadToS3(req.file.buffer, req.file.originalname);
  res.json({ uploaded: true });
});

Custom storage configuration -- control filenames and destination

import { v4 as uuid } from "uuid";

const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, "uploads/avatars/");
  },
  filename: (req, file, cb) => {
    const ext = file.originalname.split(".").pop();
    cb(null, `${uuid()}.${ext}`);   // avoid filename collisions/overwrites
  },
});

const upload = multer({ storage });

Handling multer errors properly

import multer from "multer";

app.post("/upload", (req, res, next) => {
  upload.single("avatar")(req, res, (err) => {
    if (err instanceof multer.MulterError) {
      if (err.code === "LIMIT_FILE_SIZE") {
        return res.status(400).json({ error: "File too large (max 5MB)" });
      }
      return res.status(400).json({ error: err.message });
    } else if (err) {
      return res.status(400).json({ error: err.message });   // fileFilter errors
    }
    next();
  });
}, (req, res) => {
  res.json({ filename: req.file.filename });
});

Uploading directly to cloud storage (S3)

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
const s3 = new S3Client({ region: "ap-south-1" });

app.post("/upload", memoryUpload.single("photo"), async (req, res) => {
  const key = `uploads/${uuid()}-${req.file.originalname}`;

  await s3.send(new PutObjectCommand({
    Bucket: "my-app-uploads",
    Key:    key,
    Body:   req.file.buffer,
    ContentType: req.file.mimetype,
  }));

  res.json({ url: `https://my-app-uploads.s3.amazonaws.com/${key}` });
});

Streaming large uploads and security considerations

// For VERY large files, avoid buffering the entire file in memory --
// stream it directly to its destination:
import { pipeline } from "stream/promises";

app.post("/upload-large", async (req, res) => {
  // busboy (which multer is built on) can be used directly for streaming control:
  const busboy = Busboy({ headers: req.headers });

  busboy.on("file", async (fieldname, fileStream, info) => {
    const writeStream = createWriteStream(`uploads/${info.filename}`);
    await pipeline(fileStream, writeStream);   // streams without buffering it all in RAM
  });

  req.pipe(busboy);
  busboy.on("finish", () => res.json({ uploaded: true }));
});

Security: never trust client-reported file type

file.mimetype comes from the Content-Type header the CLIENT sets in the multipart request — it is trivially spoofable. A malicious user can rename a .exe to photo.jpg and set whatever mimetype they want. For genuine security, inspect the actual file bytes ("magic numbers") with a library like file-type, which reads the binary signature rather than trusting metadata. Additionally: always validate/regenerate filenames (never use the client-provided name directly in a file path — path traversal via ../../etc/passwd is a real attack), store uploads outside your web server's static-serving root unless intentionally public, and scan uploads for malware if accepting files from untrusted users at scale.

Official Sources

The Codex links only to official documentation. No third-party tutorials.