Users need to upload files: profile pictures, documents, resumes, attachments. Handling this in Express requires special handling. A library called Multer makes it straightforward.
Why File Uploads Need Special Handling
Regular form data is text. But files are binary. When uploading files, the request format changes to multipart/form-data, which handles both text fields and binary files.
Express doesn't automatically parse this format. That's where Multer comes in.
What is Multer?
Multer is middleware for Express that handles file uploads. It parses multipart form data, extracts files, and saves them to disk or memory.
Install it:
npm install multer
Basic File Upload
Set up Multer to handle a single file:
import express from 'express';
import multer from 'multer';
const app = express();
const upload = multer({ dest: 'uploads/' });
app.post('/upload', upload.single('file'), (req, res) => {
if (!req.file) {
return res.status(400).send('No file uploaded');
}
res.send(`File ${req.file.filename} uploaded`);
});
app.listen(3000);
multer({ dest: 'uploads/' }) saves files to the uploads/ folder
upload.single('file') handles one file from a form field named "file"
req.file contains file information
A user posts a file to /upload, and Multer saves it to uploads/.
After upload, req.file contains:
{
fieldname: 'file',
originalname: 'photo.jpg',
encoding: '7bit',
mimetype: 'image/jpeg',
destination: 'uploads/',
filename: 'file-1234567890',
path: 'uploads/file-1234567890',
size: 154321
}
Use this information to track what was uploaded:
app.post('/upload', upload.single('file'), (req, res) => {
if (!req.file) {
return res.status(400).send('No file uploaded');
}
res.json({
message: 'File uploaded successfully',
filename: req.file.filename,
originalName: req.file.originalname,
size: req.file.size,
path: req.file.path
});
});
Multiple File Uploads
Handle multiple files with upload.array():
import express from 'express';
import multer from 'multer';
const app = express();
const upload = multer({ dest: 'uploads/' });
app.post('/upload-multiple', upload.array('files'), (req, res) => {
if (!req.files || req.files.length === 0) {
return res.status(400).send('No files uploaded');
}
const fileInfo = req.files.map(file => ({
filename: file.filename,
originalName: file.originalname,
size: file.size
}));
res.json({ files: fileInfo });
});
app.listen(3000);
req.files is an array of uploaded files.
You can limit the number of files:
upload.array('files', 5) // Max 5 files
Customizing File Names
By default, Multer generates random filenames. Configure storage to control this:
import express from 'express';
import multer from 'multer';
import path from 'path';
const app = express();
const storage = multer.diskStorage({
destination: (req, file, cb) => {
cb(null, 'uploads/');
},
filename: (req, file, cb) => {
// Keep original extension
const ext = path.extname(file.originalname);
const name = path.basename(file.originalname, ext);
const uniqueName = name + '-' + Date.now() + ext;
cb(null, uniqueName);
}
});
const upload = multer({ storage });
app.post('/upload', upload.single('file'), (req, res) => {
res.json({ filename: req.file.filename });
});
app.listen(3000);
Now files are named: photo-1234567890.jpg instead of random names.
Filtering File Types
Validate file types to prevent unwanted uploads:
import express from 'express';
import multer from 'multer';
const app = express();
const storage = multer.diskStorage({
destination: 'uploads/',
filename: (req, file, cb) => {
cb(null, Date.now() + '-' + file.originalname);
}
});
const fileFilter = (req, file, cb) => {
// Allow only images
const allowedMimes = ['image/jpeg', 'image/png', 'image/gif'];
if (allowedMimes.includes(file.mimetype)) {
cb(null, true);
} else {
cb(new Error('Only image files are allowed'));
}
};
const upload = multer({ storage, fileFilter });
app.post('/upload-image', upload.single('image'), (req, res) => {
res.json({ message: 'Image uploaded', filename: req.file.filename });
});
app.listen(3000);
The fileFilter function checks the MIME type and rejects non-image files.
Limiting File Size
Prevent huge files from being uploaded:
const upload = multer({
dest: 'uploads/',
limits: {
fileSize: 5 * 1024 * 1024 // 5MB
}
});
app.post('/upload', upload.single('file'), (req, res) => {
res.json({ message: 'File uploaded' });
});
Files larger than 5MB are rejected.
Handling Multiple File Fields
Upload different types of files in one request:
const app = express();
const upload = multer({ dest: 'uploads/' });
const fileUpload = upload.fields([
{ name: 'profilePic', maxCount: 1 },
{ name: 'coverPhoto', maxCount: 1 },
{ name: 'documents', maxCount: 5 }
]);
app.post('/upload-profile', fileUpload, (req, res) => {
const profilePic = req.files.profilePic?.[0];
const coverPhoto = req.files.coverPhoto?.[0];
const documents = req.files.documents;
res.json({
profilePic: profilePic?.filename,
coverPhoto: coverPhoto?.filename,
documentCount: documents?.length || 0
});
});
app.listen(3000);
req.files contains objects for each field name.
Complete Realistic Example
Here's a complete user profile upload system:
import express from 'express';
import multer from 'multer';
import path from 'path';
import { fileURLToPath } from 'url';
const app = express();
const __dirname = path.dirname(fileURLToPath(import.meta.url));
app.use(express.json());
// Configure storage
const storage = multer.diskStorage({
destination: (req, file, cb) => {
const uploadDir = 'uploads/profiles';
cb(null, uploadDir);
},
filename: (req, file, cb) => {
const ext = path.extname(file.originalname);
const name = 'profile-' + Date.now() + ext;
cb(null, name);
}
});
// Filter to allow only images
const fileFilter = (req, file, cb) => {
const allowedMimes = ['image/jpeg', 'image/png'];
if (allowedMimes.includes(file.mimetype)) {
cb(null, true);
} else {
cb(new Error('Only JPEG and PNG images allowed'));
}
};
const upload = multer({
storage,
fileFilter,
limits: { fileSize: 2 * 1024 * 1024 } // 2MB
});
// Serve uploaded files
app.use('/images', express.static('uploads/profiles'));
// Upload endpoint
app.post('/upload-profile', upload.single('profilePic'), (req, res) => {
if (!req.file) {
return res.status(400).json({ error: 'No file uploaded' });
}
const imageUrl = `/images/${req.file.filename}`;
res.json({
message: 'Profile picture uploaded',
filename: req.file.filename,
url: imageUrl,
size: req.file.size
});
});
// Error handler for Multer
app.use((err, req, res, next) => {
if (err instanceof multer.MulterError) {
if (err.code === 'FILE_TOO_LARGE') {
return res.status(400).json({ error: 'File too large' });
}
return res.status(400).json({ error: err.message });
}
if (err) {
return res.status(400).json({ error: err.message });
}
next();
});
app.listen(3000, () => {
console.log('Server running on port 3000');
});
Memory Storage
Store files in memory instead of disk (useful for processing before saving):
const storage = multer.memoryStorage();
const upload = multer({ storage });
app.post('/process-file', upload.single('file'), (req, res) => {
// File is in req.file.buffer (as a Buffer)
const content = req.file.buffer.toString();
res.json({ message: 'File processed' });
});
Common Mistakes
Mistake 1: Not handling errors
// Wrong - crashes on file too large
app.post('/upload', upload.single('file'), (req, res) => {
res.send('Done');
});
// Right - add error handler
app.use((err, req, res, next) => {
if (err instanceof multer.MulterError) {
res.status(400).json({ error: err.message });
} else {
res.status(500).json({ error: 'Server error' });
}
});
Mistake 2: Trusting original filename
// Wrong - security risk
const filename = file.originalname;
// Right - generate safe filename
const filename = Date.now() + '-' + file.originalname;
Mistake 3: Not validating file type
Always validate using MIME type or file extension, preferably both.
Key Takeaways
Multer is middleware for handling file uploads in Express
Use upload.single() for one file, upload.array() for multiple
Configure storage to control where and how files are saved
Use fileFilter to validate file types
Set size limits to prevent huge uploads
Always generate unique, safe filenames
Use error handlers to gracefully handle upload errors
Serve uploaded files as static files with express.static
File uploads are common in web applications. Master Multer, and you can confidently handle user-uploaded content.
