Multer — File Upload Middleware for Node.js

Introduction

Multer handles multipart/form-data requests in Node.js, parsing file uploads and making them available via req.file or req.files. It plugs into Express as middleware and supports disk storage, memory storage, and custom storage engines.

What Multer Does

• Parses multipart/form-data requests and extracts uploaded files
• Stores files to disk or memory with configurable storage engines
• Limits file size, field count, and number of files per request
• Filters files by MIME type or custom validation before saving
• Populates req.file (single) or req.files (multiple) with upload metadata

Architecture Overview

Multer wraps the busboy streaming multipart parser. When a request hits the middleware, busboy parses the multipart boundary, streaming each file part through the configured storage engine. The disk storage engine writes to a destination directory with a generated filename, while memory storage buffers the file in a Buffer object. Text fields are collected into req.body. Multer operates as standard Express middleware and does not buffer the entire request before processing.

Self-Hosting & Configuration

• Install via npm: npm install multer
• Use multer({ dest: './uploads' }) for quick disk storage with auto-generated filenames
• Use multer.diskStorage({ destination, filename }) for full control over paths and names
• Use multer.memoryStorage() to keep files in memory as Buffer objects for processing
• Set limits: { fileSize: 5 * 1024 * 1024 } to cap uploads at 5 MB

Key Features

• Streaming parser handles large files without loading everything into memory at once
• Multiple upload modes: .single(), .array(), .fields(), and .any()
• Custom storage engines allow writing to S3, GCS, or any backend via the storage API
• File filter callback lets you accept or reject files based on type or other criteria
• Non-file fields are still parsed and available in req.body

Comparison with Similar Tools

• Formidable — standalone multipart parser with no Express dependency; Multer is Express middleware
• Busboy — lower-level streaming parser that Multer wraps with a higher-level API
• express-fileupload — simpler API but buffers files in memory by default
• Multiparty — similar to Formidable; Multer offers tighter Express integration

FAQ

Q: Does Multer handle non-file form fields? A: Yes. Text fields in the multipart request are parsed and placed in req.body.

Q: Can I upload to cloud storage like S3? A: Yes. Use community storage engines like multer-s3 or write a custom storage engine implementing _handleFile and _removeFile.

Q: How do I validate file types? A: Pass a fileFilter function to the Multer options that checks file.mimetype and calls the callback with true or false.

Q: What happens if the upload exceeds the size limit? A: Multer emits a LIMIT_FILE_SIZE error that you can catch in Express error-handling middleware.

Sources

• https://github.com/expressjs/multer
• https://www.npmjs.com/package/multer