How to Handle multipart/form-data in Express.js

Posted by on

 

How to Handle multipart/form-data in Express.js (Complete Guide)

When building web applications, you will often encounter multipart/form-data, especially when working with file uploads or forms that contain mixed data. In Express.js, handling multipart requests requires a specialized middleware because Express cannot parse multipart bodies by default.
The most widely used solution is Multer — a middleware designed specifically for handling multipart/form-data.

This article explains what multipart/form-data is, when you need Multer, and how to correctly handle various scenarios in Express.js.

What is multipart/form-data?

multipart/form-data is an encoding type used when submitting forms that contain:

  • Files (images, PDFs, documents)

  • Mixed form data (text + file)

  • Large binary data

The browser divides the form data into multiple parts (hence “multipart”) and sends it in a way that can carry both text and binary content.

Because of this structure, Express cannot parse it automatically, even when using:

express.urlencoded()
express.json()

This is where Multer comes in.

Installing Multer

npm install multer

Multer will help Express extract the text fields and file content from multipart requests.

Configuring Multer

Most applications that accept file uploads save them to the server. Multer supports memory or disk storage; here’s a basic disk storage setup:

import multer from "multer";
import path from "path";

const storage = multer.diskStorage({
  destination: "uploads/",
  filename: (req, file, cb) => {
    cb(null, Date.now() + path.extname(file.originalname));
  }
});

const upload = multer({ storage });

Use Cases of multipart/form-data in Express

1. Uploading a Single File

When your form includes a single file input:

<input type="file" name="photo">

The Express route:

app.post("/upload", upload.single("photo"), (req, res) => {
  console.log(req.file);  
  console.log(req.body);
  res.send("File uploaded successfully!");
});

2. Uploading Multiple Files

app.post("/gallery", upload.array("photos", 10), (req, res) => {
  console.log(req.files);
  res.send("Multiple files uploaded!");
});

3. Uploading Files Under Different Field Names

app.post("/documents", upload.fields([
  { name: "aadhar", maxCount: 1 },
  { name: "photo", maxCount: 1 }
]), (req, res) => {
  console.log(req.files);
  console.log(req.body);
});

Handling multipart/form-data with NO Files

Sometimes the form uses multipart/form-data even though it does not upload files. For example:

<form enctype="multipart/form-data">
  <input type="text" name="username">
  <button type="submit">Submit</button>
</form>

In this case, Express still cannot parse the body without Multer.
To handle text-only multipart forms, Multer provides:

app.post("/submit", upload.none(), (req, res) => {
  console.log(req.body);
  res.send("Text fields received!");
});

Why is upload.none() required?

Because:

  • The form uses multipart/form-data

  • Express cannot parse multipart on its own

  • Multer must parse the multipart content

  • upload.none() tells Multer to only extract text fields and ignore any files

When Multer is NOT required

If your form does not upload files, you should NOT use multipart/form-data.

Instead, use the default form encoding:

<form enctype="application/x-www-form-urlencoded">

Then enable Express’s built-in parsers:

app.use(express.urlencoded({ extended: true }));
app.use(express.json());

This avoids unnecessary overhead.

Best Practices for Handling multipart/form-data

✔ Use Multer only when your form uses multipart

Do not use Multer for normal text forms.

✔ Use upload.none() for text-only multipart

This avoids errors like:

Unexpected field

✔ Keep upload directory secure

Never expose “uploads/” directly without proper access rules.

✔ Validate file types

Always verify file extensions and MIME types before saving.

✔ Use memory storage for temporary processing

If you want to upload directly to cloud storage (S3, Cloudinary), use memory storage instead of local disk.

Conclusion

Handling multipart/form-data in Express.js is simple once you understand when and why to use Multer.
Use Multer for any multipart form, even if it contains only text fields. Use Express’s built-in body parsers for regular forms.

By choosing the right approach based on your form structure, you ensure efficient, secure, and error-free handling of file uploads and form submissions in your Express applications.

Naba Kumar Chouhan

Comments

Post a Comment