Express.js · Module

multer

Multer is Express middleware for parsing multipart/form-data, mainly to support file uploads. It adds text fields and uploaded files to the request object and can be configured for disk or custom storage.

How it works

Multer is third-party middleware for Express that parses multipart/form-data requests, typically for file uploads. It attaches submitted text fields to req.body and uploaded files to req.file or req.files, depending on the upload method, while storage options determine where files go.

Syntax

multer(options)

Parameters

Name	Type	Description
`options`	`object`	Options used to configure Multer, including destination or storage behavior.
`fieldname`	`string`	The multipart form field name whose single uploaded file should be accepted.
`maxCount`	`number`	The maximum number of files accepted for an array field.
`fields`	`array`	A list describing accepted field names and their per-field file limits.

Returns

A configured Multer instance whose methods return Express middleware for parsing multipart/form-data requests.

Key points

It parses multipart requests in Node.js and is chiefly intended for handling file uploads.
After parsing, text fields are available on req.body, while files appear on req.file or req.files.
Storage configuration can specify destination, filename, and flush behavior.
The destination and filename settings can be functions, allowing storage location and naming to be computed dynamically.
The none() middleware is intended for multipart requests that contain fields but no uploaded files.
Its default parsing path pipes the incoming request into Busboy.
Calling the generated middleware directly enables application code to catch and classify upload errors itself.

Common mistakes

The request must use multipart/form-data; ordinary URL-encoded or JSON forms are not handled.
HTML forms must declare the multipart encoding or the browser will not send files in the expected format.
The field name passed to methods such as single() must match the form control's name exactly.
Upload failures enter Express's normal error-handling flow unless the middleware is invoked manually for specialized handling.

Example: Single-file upload with Multer

const express = require('express');
const multer = require('multer');

const upload = multer({ dest: 'uploads/' });
const app = express();

app.post('/profile', upload.single('avatar'), (req, res) => {
  res.json({ fields: req.body, file: req.file });
});

app.listen(3000);

This route accepts a multipart form containing an avatar field, stores the uploaded file in the configured directory, and exposes text fields through req.body and the uploaded file through req.file.

When to use it

Single-file upload

A profile form sends one avatar image.

Multiple files for one field

A form submits several photos under one field.

Text-only multipart parsing

A multipart request contains text fields but no files.

Custom storage rules

Uploads require application-specific names or destinations.

Interview questions

QWhat problem does Multer solve in an Express application?

Multer handles multipart/form-data requests and adds text fields to req.body. Uploaded data is exposed on req.file or req.files according to the configured upload middleware.

Follow-up: How would you reject only Multer-specific failures? Use multer.MulterError and test the caught error with instanceof.

QHow do you configure and apply Multer?

Use multer(options) to create an upload middleware, then choose an operation such as single(fieldname), array(fieldname, maxCount), fields(fields), any(), or none(). The selected operation controls which files are accepted and where they appear on the request.

Follow-up: What operation handles a multipart request containing only text fields? Use none(), which rejects file uploads while parsing the multipart fields.

QHow does Multer determine where uploaded files are stored?

A destination can be supplied directly through the dest option for simple disk-backed uploads. For more control, storage configuration uses destination and filename functions to determine the file location and name.

Follow-up: What should be considered before using any()? It accepts files from all fields, so a route should use more restrictive middleware when the accepted field set is known.

express
multipart/form-data
busboy
MulterError
req.body
req.file
req.files
diskStorage

Source: multer middleware. Checked 2026-10-15.