# Handling File Uploads in Express with Multer

## Handling File Uploads in Express with Multer

When building real-world backend systems, handling file uploads is unavoidable—profile pictures, documents, PDFs, etc. But unlike JSON data, file uploads require a different handling mechanism. This is where middleware like **Multer** becomes essential.

* * *

## Why File Uploads Need Middleware

In a typical Express.js application running on Node.js, request bodies are usually parsed using middleware like `express.json()` or `express.urlencoded()`.

However, file uploads are sent using a special encoding type:

### 👉 `multipart/form-data`

This format:

*   Breaks the request body into **multiple parts**
    
*   Each part can contain **text fields or files**
    
*   Cannot be parsed by default Express body parsers
    

So without middleware, Express simply **cannot read file data**.

* * *

## What is Multer?

Multer is a middleware specifically designed to handle `multipart/form-data`.

It:

*   Parses incoming file data
    
*   Stores files (locally or memory)
    
*   Attaches file info to the request object
    

Think of Multer as a **bridge between raw file data and usable JavaScript objects**.

* * *

## Understanding the Upload Lifecycle

Here’s what happens when a file is uploaded:

1.  Client sends a form with `multipart/form-data`
    
2.  Request reaches Express
    
3.  Multer intercepts the request
    
4.  File is processed and stored
    
5.  File metadata is attached to:
    
    *   `req.file` (single file)
        
    *   `req.files` (multiple files)
        
6.  Your route handler uses this data
    

* * *

## Installing Multer

```bash
npm install multer
```

* * *

## Basic Setup

```js
const express = require("express");
const multer = require("multer");

const app = express();
```

* * *

## Storage Configuration (Basic)

By default, Multer stores files in memory. But usually, you want local storage.

```js
const storage = multer.diskStorage({
  destination: function (req, file, cb) {
    cb(null, "uploads/");
  },
  filename: function (req, file, cb) {
    cb(null, Date.now() + "-" + file.originalname);
  }
});

const upload = multer({ storage });
```

### Key Concepts:

*   **destination** → where file is stored
    
*   **filename** → how file is named
    

* * *

## Handling Single File Upload

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

### Important:

*   `"profile"` must match the form input name
    
*   File info is available in `req.file`
    

* * *

## Handling Multiple File Uploads

### Option 1: Multiple files with same field

```js
app.post("/upload-multiple", upload.array("photos", 5), (req, res) => {
  console.log(req.files);
  res.send("Multiple files uploaded");
});
```

*   `"photos"` → field name
    
*   `5` → max number of files
    

* * *

### Option 2: Different fields

```js
app.post("/upload-fields", upload.fields([
  { name: "avatar", maxCount: 1 },
  { name: "documents", maxCount: 3 }
]), (req, res) => {
  console.log(req.files);
  res.send("Files uploaded");
});
```

* * *

## Serving Uploaded Files

Once files are stored locally, you need to serve them.

```js
app.use("/uploads", express.static("uploads"));
```

Now files are accessible via:

```plaintext
http://localhost:3000/uploads/filename.jpg
```

* * *

## Example HTML Form

```html
<form action="/upload" method="POST" enctype="multipart/form-data">
  <input type="file" name="profile" />
  <button type="submit">Upload</button>
</form>
```

### Key Point:

*   `enctype="multipart/form-data"` is **mandatory**
    

* * *

## Common Mistakes to Avoid

*   ❌ Forgetting `enctype="multipart/form-data"`
    
*   ❌ Mismatched field name between form and Multer
    
*   ❌ Not creating the `uploads/` directory
    
*   ❌ Trying to use `express.json()` for file uploads
    

* * *

## Minimal Mental Model

*   Express alone → handles JSON/text
    
*   Multer → handles files
    
*   multipart/form-data → required format
    

* * *

## When to Use Multer

Use Multer when:

*   Uploading profile images
    
*   Uploading documents (PDF, resumes)
    
*   Handling media files
    

Avoid overcomplicating early:

*   Don’t jump to cloud storage yet (S3, Cloudinary)
    
*   First master **local uploads + serving**
    

* * *