NodeJS File Upload Tutorial: A Complete Guide with Express and Multer

Want to learn how to handle file uploads in your NodeJS application? This guide provides a step-by-step walkthrough for building a robust backend API using Express, TypeScript, and Multer. Get ready to handle file uploads with ease!

This tutorial focuses on simple file upload functionality, saving files with their original names without file type restrictions or size limits.

Why Use NodeJS, Express, and Multer for File Uploads?

• NodeJS: A JavaScript runtime environment ideal for building scalable and efficient backend applications.
• Express: A minimalist web framework for NodeJS that simplifies routing and middleware management.
• Multer: A middleware for handling multipart/form-data, essential for file uploads.

Project Setup: Your File Upload API Structure

Here's the breakdown of the project's directory 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 1: Install NodeJS Dependencies

Kickstart your project by installing the necessary packages:

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

Create tsconfig.json file with the following basic configuration:

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

Step 2: Configure Multer Middleware for NodeJS File Upload

Create middleware/upload.middleware.ts:

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 code sets up Multer to store uploaded files in the "uploads" directory.
• The filename function adds a timestamp to the original filename to prevent conflicts.
• Make sure the uploads directory exists.

Step 3: Build the Upload Service

Create services/upload.service.ts:

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 extracts relevant information from the uploaded file object and returns a formatted response.

Step 4: Craft the Upload Controller

Create controllers/upload.controller.ts:

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);
};

The controller checks if a file was uploaded and then utilizes the handleUploadService to process the file and send a success response.

Step 5: Define the File Upload Route

Create routes/upload.route.ts:

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;

This route uses the upload.single('file') middleware to handle a single file upload named "file".

Step 6: Initialize the Express Server for NodeJS File Upload

Create index.ts:

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 initializes the Express server, uses the express.json() middleware and mounts the upload route.

Test Your NodeJS File Upload API

Use Postman or a similar tool to test the API endpoint:

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

You should receive a JSON response similar to:

{
  "message": "File uploaded successfully!",
  "originalName": "video.mp4",
  "filename": "1713967431914-video.mp4",
  "path": "/uploads/1713967431914-video.mp4",
  "size": 123456
}

Conclusion

Congratulations! You've built a functional file upload API using NodeJS, Express, and Multer. This setup provides a solid foundation for more advanced file handling features. This should allow you to easily implement image uploads and more!