In this post, I'll explain how to use Multer with Node.js and Express.js to upload files, specify where they should be stored, and validate the types of files users are allowed to upload.

What is Multer?

Multer is a middleware library used with Node.js and Express.js to handle file uploads.

The problem is that Express can handle JSON and URL-encoded data by default, but it cannot process multipart/form-data, which is the format used when uploading files such as images, videos, and documents.

This is where Multer comes in. It parses multipart/form-data requests and allows the server to receive and process uploaded files easily, whether by storing them locally on the server or sending them to an external storage service.

Simply put, Multer acts as the bridge that enables a Node.js server to receive and work with uploaded files.

Let's dive into the important details.

After installing Multer, we can configure it inside the route responsible for handling file uploads.

import multer from "multer"; 
// File upload destination 
// Make sure the folder already exists 
const upload = multer({ dest: "./uploads" });

app.post("/submit", upload.single("profile"), (req, res) => { 
    // File information is available here 
    console.log(req.file); 
    res.send("File uploaded"); 
});

Explanation

dest: './uploads' → Specifies the folder where uploaded files will be stored.
upload.single("profile") → Indicates that we're uploading a single file with the field name profile.
req.file → Contains information about the uploaded file, including its name, path, size, and MIME type.

Important Note About the Previous Approach

Although the previous code works, it introduces several issues in real-world applications:

Random File Names
1. When using: { dest: "./uploads" }
2. Multer automatically generates a random filename without preserving the original extension.
3. This can make it difficult to identify file types or manage files later.
No File Validation
1. The current setup allows users to upload any file type, including images, videos, and potentially dangerous files such as .exe files.
2. This can create security risks and unnecessary storage issues.

A Better Approach: Using diskStorage

Instead of relying on dest, we can use diskStorage to:
- Control the final file name.
- Preserve the file extension.
- Filter allowed file types.

This approach is much safer and more suitable for production applications.

import multer from "multer";

const diskStorage = multer.diskStorage({ 
    destination: function (req, file, cb) { 
        cb(null, "uploads");
    }, 
    filename: function (req, file, cb) { 
        const ext = file.mimetype.split("/")[1]; 
        const fileName = `user-${Date.now()}.${ext}`; cb(null, fileName); 
    }, 
});

const fileFilter = (req, file, cb) => { 
    const imageType = file.mimetype.split("/")[0]; 

    if (imageType === "image") { 
        cb(null, true); 
    } 
    else { 
        cb(appError.create("file must be an image", 400), false);
    }
};


const upload = multer({ 
    storage: diskStorage, 
    fileFilter,
}); 

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

Step-by-Step Explanation

diskStorage

const diskStorage = multer.diskStorage({ 
    destination: function (req, file, cb) { 
        cb(null, "uploads");
    }, 
    filename: function (req, file, cb) { 
        const ext = file.mimetype.split("/")[1]; 
        const fileName = `user-${Date.now()}.${ext}`; cb(null, fileName); 
    }, 
});

destination
- Defines where uploaded files will be stored on the server.
filename
- Allows us to generate a custom filename such as: user-1729452123456.png
- instead of using a random filename.
Benefit: Easier file management and better organization.

2. fileFilter

const fileFilter = (req, file, cb) => { 
    const imageType = file.mimetype.split("/")[0]; 

    if (imageType === "image") { 
        cb(null, true); 
    } 
    else { 
        cb(appError.create("file must be an image", 400), false);
    }
};

This function restricts uploads to image files only.
Any other file type is rejected before being stored.
Benefit: Protects your application from unwanted or potentially dangerous file uploads.

3. Creating the Multer Instance

const upload = multer({ 
    storage: diskStorage, 
    fileFilter,
});

Here, we combine both:

Custom storage configuration.
File type validation.

This gives us full control over how files are uploaded and managed

4. The Route

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

upload.single("profile")
- Handles a single uploaded file from the profile field.
req.file
- Contains all file metadata, including:
  - File name
  - Path
  - Size
  - MIME type
  - Upload information

Problems Solved

Random file names without extensions → Solved using filename inside diskStorage.
Uploading any file type → Solved using fileFilter.
Limited control over storage behavior → Solved using diskStorage.

Important Notes About Local File Storage

The approach shown above works perfectly in a local development environment
However, once you deploy your application to platforms such as Vercel or Netlify, you'll likely encounter issues because these environments do not support persistent local file storage. Uploaded files may disappear after deployments, server restarts, or scaling events
In addition, storing files locally:
- Increases server storage usage.
- Makes file management more difficult.
- Reduces scalability.
A better solution is to upload files directly to cloud storage services such as Cloudinary or AWS S3. These services provide better scalability, security, availability, and file management.

In the next post, I'll explain how to upload files to Cloudinary step by step.

Mastering File Uploads in Node.js with Multer: Storage, Validation, and Best Practices