Build a Node.js File Upload API with Express and Multer

Want to add file upload functionality to your Node.js application? This guide provides a step-by-step approach using Express, TypeScript, and Multer. Learn to build a clean, reusable backend API for handling file uploads easily.

Why Use Multer for File Uploads in Node.js?

Multer is middleware for Node.js that simplifies handling multipart/form-data, which is essential for file uploads. It streamlines the process of receiving and processing files on your server.

Tech Stack for Our File Upload API

• Express: A fast, minimalist web framework for Node.js.
• Multer: Middleware for handling multipart/form-data.
• TypeScript: Adds optional static typing to your JavaScript code, improving maintainability.
• MVC Structure: Organizes your code for clarity and scalability.

Project Structure: Keep it Clean

Organize your project with a clear folder structure:

file-upload-api/
├── controllers/
│   └── upload.controller.ts
├── middleware/
│   └── upload.middleware.ts
├── routes/
│   └── upload.route.ts
├── services/
│   └── upload.service.ts
├── uploads/ (created automatically)
├── index.ts
├── tsconfig.json
└── package.json

Step-by-Step Guide to Building a Node.js File Upload API

Let's create a simple file upload API.

Step 1: Installing the Necessary Dependencies

First, install the packages you'll be using:

npm install express multer
npm install -D typescript ts-node-dev @types/node @types/express @types/multer

Create a tsconfig.json if you don't already have one:

{
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["./**/*.ts"]
}

Step 2: Configure Multer Middleware

Create middleware/upload.middleware.ts to handle file storage:

import multer from 'multer';
import path from 'path';
import fs from 'fs';

// Ensure uploads directory exists
const uploadDir = path.join(process.cwd(), 'uploads');
if (!fs.existsSync(uploadDir)) {
  fs.mkdirSync(uploadDir, { recursive: true });
}

const storage = multer.diskStorage({
  destination: (_req, _file, cb) => cb(null, uploadDir),
  filename: (_req, file, cb) => {
    const timestamp = Date.now();
    cb(null, `${timestamp}-${file.originalname}`);
  },
});

export const upload = multer({ storage });

This middleware configures Multer to save uploaded files to the uploads directory, prefixing the original filename with a timestamp to prevent collisions.

Step 3: Implementing the Upload Service

Create services/upload.service.ts to process the uploaded file details:

export const handleUploadService = (file: Express.Multer.File) => {
  return {
    message: 'File uploaded successfully!',
    originalName: file.originalname,
    filename: file.filename,
    path: file.path,
    size: file.size,
  };
};

This service formats the file information into a user-friendly object.

Step 4: Create the File Upload Controller

Create controllers/upload.controller.ts to handle the upload request:

import { Request, Response } from 'express';
import { handleUploadService } from '../services/upload.service';

export const uploadFile = (req: Request, res: Response) => {
  if (!req.file) {
    return res.status(400).json({ error: 'No file uploaded' });
  }

  const data = handleUploadService(req.file);
  res.status(200).json(data);
};

This controller checks for a file, processes it using the upload service, and sends a response.

Step 5: Define the API Route for Node.js File Upload

Create routes/upload.route.ts to define the API endpoint:

import { Router } from 'express';
import { upload } from '../middleware/upload.middleware';
import { uploadFile } from '../controllers/upload.controller';

const router = Router();
router.post('/file', upload.single('file'), uploadFile);

export default router;

Here, we define a route /file that uses the Multer middleware to handle a single file upload named "file".

Step 6: Setting Up the Express Server

Create index.ts to initialize the Express server and connect the route:

import express from 'express';
import uploadRoute from './routes/upload.route';

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

app.use(express.json());
app.use('/api/upload', uploadRoute);

app.listen(PORT, () => {
  console.log(`Server running at http://localhost:${PORT}`);
});

This code starts an Express server that listens on port 3000 and uses the upload route you've created.

Testing Your File Upload API

Use Postman or a similar tool to test your API which simplifies testing file uploads in Node.js.

• Method: POST
• URL: http://localhost:3000/api/upload/file
• Body: form-data
  • Key: file (Type: File)
  • Select a file from your system

If successful, you'll receive a JSON response containing file details, similar to:

{
  "message": "File uploaded successfully!",
  "originalName": "example.pdf",
  "filename": "1713967431914-example.pdf",
  "path": "/uploads/1713967431914-example.pdf",
  "size": 456789
}

Conclusion

You now have a functional and well-structured Node.js file upload API using Express, TypeScript, and Multer. This setup provides a solid foundation for building more complex file handling features in your applications. Embrace this stack for scalable and maintainable solutions.