Multer para JavaScript (Node.js): guía completa con ejemplos

1. ¿Qué es y para qué sirve?

Multer es una popular librería middleware para Node.js, diseñada para procesar datos en formato multipart/form-data, el estándar utilizado al subir archivos desde formularios HTML. A diferencia del módulo estándar body-parser, que solo maneja JSON y datos codificados en URL, Multer puede analizar solicitudes compuestas, extraer archivos y guardarlos en el servidor (en memoria o en disco). Está construida sobre el módulo busboy y ofrece una API sencilla para configurar rutas, nombres de archivos, filtros de tipo y límites de tamaño.

¿Para qué sirve Multer? En cualquier aplicación web donde un usuario pueda subir un avatar, un documento, una imagen o un video, es necesario procesar multipart/form-data. Express.js (el framework más popular para Node.js) no tiene soporte nativo para este formato, por lo que Multer se convierte en una herramienta indispensable. Permite al desarrollador centrarse en la lógica de negocio, evitando el tedioso análisis de datos binarios a bajo nivel.

Multer soporta la subida de uno o varios archivos simultáneamente, el manejo de campos de formulario, la generación personalizada de nombres de archivo, el filtrado por tipos MIME y extensiones, así como la limitación del tamaño de los datos subidos. Gracias a su configuración flexible, la librería es adecuada tanto para proyectos simples (como la subida de avatares) como para sistemas complejos con almacenamiento en la nube (a través de almacenes personalizados).

2. Instalación

La instalación se realiza mediante npm (Node Package Manager). Asegúrate de tener Node.js instalado (versión 12 o superior).

npm install multer

Una vez instalada, la librería estará disponible para importarla en tu proyecto.

3. Inicio rápido — ejemplo mínimo funcional

Creemos un servidor simple con Express.js que reciba la subida de un archivo desde un formulario y lo guarde en la carpeta uploads/.

Paso 1. Estructura del proyecto

mkdir multer-ejemplo
cd multer-ejemplo
npm init -y
npm install express multer
touch index.html
touch server.js

Paso 2. Formulario HTML (index.html)

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8">
    <title>Subir archivo</title>
</head>
<body>
    <h1>Sube tu archivo</h1>
    <form action="/upload" method="POST" enctype="multipart/form-data">
        <input type="file" name="miArchivo" required>
        <button type="submit">Enviar</button>
    </form>
</body>
</html>

Paso 3. Servidor (server.js)

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

const app = express();
const PORT = 3000;

// Configuración de Multer: los archivos se guardarán en la carpeta 'uploads/'
const storage = multer.diskStorage({
    destination: (req, file, cb) => {
        cb(null, 'uploads/');
    },
    filename: (req, file, cb) => {
        // Generamos un nombre único: fecha actual + extensión original
        const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1E9);
        cb(null, uniqueSuffix + path.extname(file.originalname));
    }
});

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

// Servir el HTML estático
app.get('/', (req, res) => {
    res.sendFile(__dirname + '/index.html');
});

// Procesar la subida del archivo
app.post('/upload', upload.single('miArchivo'), (req, res) => {
    if (!req.file) {
        return res.status(400).send('No se subió ningún archivo.');
    }
    res.send(`El archivo "${req.file.originalname}" se subió correctamente. Tamaño: ${req.file.size} bytes.`);
});

app.listen(PORT, () => {
    console.log(`Servidor iniciado en http://localhost:${PORT}`);
});