How to Handle File Uploads in Node.js with Formidable

The Formidable NPM package is a widely used library for handling file uploads in Node.js. This guide demonstrates its use through a simple project.

Below is a preview of the application you will build:

http://localhost:3000

A basic Node.js file upload application built with the Formidable NPM package

Note

This tutorial uses a basic project to keep concepts clear and simple.

Tip

If you are new to Node.js, check out the “Introduction to Node” guide for instructions on creating and running a Node.js program.

Create a New Project Directory

mkdir codesweetly-form-001

Note

You may choose any project name. This guide uses codesweetly-form-001 for demonstration.

Afterward, navigate to your project directory using the command line.

cd path/to/codesweetly-form-001

Create a package.json File

Once you’re in the app’s directory, use NPM to create a package.json file for your project.

npm init -y

Open the package.json file and delete the main field.

Tip

The main field in package.json is primarily for referencing a library’s entry file. You don’t need it here since you’re building a Node.js application, not a package.

Also, change the type field to module so you can use ECMAScript modules in this tutorial.

{
  "scripts": {
    "start": "node console.js",
    "test": "echo "Error: no test specified" && exit 1"
  },
  "type": "module"
}

Create a Form for Uploading Files

Create an ES Module for your project.

touch form-server.js

Next, open your new module and set up the form for file uploads.

form-server.js

import { createServer } from "node:http";

const server = createServer((req, res) => {
  if (req.url === "/") {
    res.writeHead(200, { "Content-Type": "text/html" });
    res.write(
      '<div style="margin: 100px auto; font-family: Arial, sans-serif; line-height: 1.5; color: #333; max-width: 600px;">',
    );
    res.write(
      '<form action="upload-file" method="post" enctype="multipart/form-data" style="border: 1px solid #ccc; padding: 30px 50px; border-radius: 5px; background-color: #f9f9f9; box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);">',
    );
    res.write(
      '<label style="display: block; margin-bottom: 30px;"><strong style="display: block; margin-bottom: 5px;">Title</strong> <input style="width: 100%; padding: 5px; border: 1px solid #ccc; border-radius: 3px;" type="text" name="title" /></label>',
    );
    res.write(
      '<input type="file" name="uploadedFile" style="display: block; margin-bottom: 20px;" />',
    );
    res.write(
      '<button type="submit" style="background-color: #007bff; color: white; padding: 10px 20px; border: none; border-radius: 3px; cursor: pointer;">Upload File</button>',
    );
    res.write("</form>");
    res.end("</div>");
  }
});

server.listen(3000, "localhost", () => {
  console.log("Server running at http://localhost:3000/");
});

Here’s what the code above does:

• Imports the createServer API from Node’s http library into the form-server.js ES Module.
• Creates and sends a form element to the client when the server receives requests to the root path (/).
• Configures the port and hostname where the server listens for client requests.

Install the Formidable Package

Run the following command in your terminal to install the formidable NPM package:

npm install formidable

Use the Formidable Module in Your Node.js Application

Add the formidable module and use it to parse form data sent from the client to the server.

form-server.js

import { createServer } from "node:http";
import formidable from "formidable";

const server = createServer((req, res) => {
  if (req.url === "/") {
    res.writeHead(200, { "Content-Type": "text/html" });
    res.write(
      '<div style="margin: 100px auto; font-family: Arial, sans-serif; line-height: 1.5; color: #333; max-width: 600px;">',
    );
    res.write(
      '<form action="upload-file" method="post" enctype="multipart/form-data" style="border: 1px solid #ccc; padding: 30px 50px; border-radius: 5px; background-color: #f9f9f9; box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);">',
    );
    res.write(
      '<label style="display: block; margin-bottom: 30px;"><strong style="display: block; margin-bottom: 5px;">Title</strong><input style="width: 100%; padding: 5px; border: 1px solid #ccc; border-radius: 3px;" type="text" name="title" /></label>',
    );
    res.write(
      '<input type="file" name="uploadedFile" style="display: block; margin-bottom: 20px;" />',
    );
    res.write(
      '<button type="submit" style="background-color: #007bff; color: white; padding: 10px 20px; border: none; border-radius: 3px; cursor: pointer;">Upload File</button>',
    );
    res.write("</form>");
    res.end("</div>");
  }

  if (req.url === "/upload-file" && req.method.toLowerCase() === "post") {
    const form = formidable();
    form.parse(req, (err, fields, files) => {
      if (err) {
        res.writeHead(err.httpCode || 400, { "Content-Type": "text/plain" });
        return res.end(`${err}`);
      }
      console.log("Title:", fields.title);
      console.log("Uploaded file:", files.uploadedFile);
      res.writeHead(200, { "Content-Type": "text/plain" });
      res.end("Uploaded file successfully!");
    });
  }
});

server.listen(3000, "localhost", () => {
  console.log("Server running at http://localhost:3000/");
});

Here’s what the code above does:

• Imports the createServer API from Node’s http library to the form-server.js ES Module.
• Creates and sends a form to the client when the server receives a request to the root path (/).
• Uses the formidable module to parse the client’s POST request to the /upload-file URL.
• Configures the port and hostname where the server listens for client requests.

AD

Run Your Application

Now that your form is set up and the server is configured, you can run the application.

node --watch form-server.js

• node: The command for running Node.js scripts or the REPL.
• --watch: The flag for activating Node’s watch mode.
• form-server.js: The JavaScript file you want Node to run.

You can also add the command to the "scripts" field of your project’s package.json file:

package.json

{
  "scripts": {
    "start": "node --watch form-server.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

By so doing, you can run your JavaScript program from your terminal like this:

npm run start

Tip

Close the server using Ctrl + C on Windows or Cmd + C on Mac.

The parse() method is an important part of the formidable API. The next section explains how it works.

What Is the Formidable parse() Method?

The parse() method lets you process a client request that contains form data. You can use it with a callback or as a promise.

Tip

If you give parse() a callback argument, it works in callback mode. If you don’t, it returns a promise.

The callback-based parse() method

The callback-based parse() method takes two arguments. Here’s how it looks:

import formidable from "formidable";

const form = formidable();

form.parse(request, callback);

• request: The client’s request (the http.IncomingMessage object)
• callback: A function that handles the form data.

The callback function has three parameters. Here’s the syntax:

function (error, fields, files) { ... }

• error: An object for handling any errors parse() finds while processing the form data.
• fields: An object containing the form fields’ names and values.
• files: An object containing details about the uploaded files.

Here’s an example:

form-server.js

import { createServer } from "node:http";
import formidable from "formidable";

const server = createServer((req, res) => {
  if (req.url === "/") {
    res.writeHead(200, { "Content-Type": "text/html" });
    res.write(
      '<div style="margin: 100px auto; font-family: Arial, sans-serif; line-height: 1.5; color: #333; max-width: 600px;">',
    );
    res.write(
      '<form action="upload-file" method="post" enctype="multipart/form-data" style="border: 1px solid #ccc; padding: 30px 50px; border-radius: 5px; background-color: #f9f9f9; box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);">',
    );
    res.write(
      '<label style="display: block; margin-bottom: 30px;"><strong style="display: block; margin-bottom: 5px;">Title</strong><input style="width: 100%; padding: 5px; border: 1px solid #ccc; border-radius: 3px;" type="text" name="title" /></label>',
    );
    res.write(
      '<input type="file" name="uploadedFile" style="display: block; margin-bottom: 20px;" />',
    );
    res.write(
      '<button type="submit" style="background-color: #007bff; color: white; padding: 10px 20px; border: none; border-radius: 3px; cursor: pointer;">Upload File</button>',
    );
    res.write("</form>");
    res.end("</div>");
  }

  if (req.url === "/upload-file" && req.method.toLowerCase() === "post") {
    const form = formidable();
    form.parse(req, (err, fields, files) => {
      if (err) {
        res.writeHead(err.httpCode || 400, { "Content-Type": "text/plain" });
        return res.end(`${err}`);
      }
      console.log("Title:", fields.title);
      console.log("Uploaded file:", files.uploadedFile);
      res.writeHead(200, { "Content-Type": "text/plain" });
      res.end("Uploaded file successfully!");
    });
  }
});

server.listen(3000, "localhost", () => {
  console.log("Server running at http://localhost:3000/");
});

The code above uses the callback-based parse() method to process the form’s data.

The promise-based version of the parse() method

The promise-based parse() method takes just one argument. Here’s how it looks:

import formidable from "formidable";

const form = formidable();

const [fields, files] = await form.parse(request);

• fields: An object containing the form fields’ names and values.
• files: An object containing details about the uploaded files.
• request: The client’s request (the http.IncomingMessage object)

Here’s an example:

form-server.js

import { createServer } from "node:http";
import formidable from "formidable";

const server = createServer((req, res) => {
  if (req.url === "/") {
    res.writeHead(200, { "Content-Type": "text/html" });
    res.write(
      '<div style="margin: 100px auto; font-family: Arial, sans-serif; line-height: 1.5; color: #333; max-width: 600px;">',
    );
    res.write(
      '<form action="upload-file" method="post" enctype="multipart/form-data" style="border: 1px solid #ccc; padding: 30px 50px; border-radius: 5px; background-color: #f9f9f9; box-shadow: 0 2px 5px rgba(0, 0, 0, 0.1);">',
    );
    res.write(
      '<label style="display: block; margin-bottom: 30px;"><strong style="display: block; margin-bottom: 5px;">Title</strong><input style="width: 100%; padding: 5px; border: 1px solid #ccc; border-radius: 3px;" type="text" name="title" /></label>',
    );
    res.write(
      '<input type="file" name="uploadedFile" style="display: block; margin-bottom: 20px;" />',
    );
    res.write(
      '<button type="submit" style="background-color: #007bff; color: white; padding: 10px 20px; border: none; border-radius: 3px; cursor: pointer;">Upload File</button>',
    );
    res.write("</form>");
    res.end("</div>");
  }

  if (req.url === "/upload-file" && req.method.toLowerCase() === "post") {
    async function processForm() {
      try {
        const form = formidable();
        const [fields, files] = await form.parse(req);
        console.log("Title:", fields.title);
        console.log("Uploaded file:", files.uploadedFile);
        res.writeHead(200, { "Content-Type": "text/plain" });
        res.end("Uploaded file successfully!");
      } catch (err) {
        res.writeHead(err.httpCode || 400, { "Content-Type": "text/plain" });
        res.end(`${err}`);
        console.error(err);
      }
    }
    processForm();
  }
});

server.listen(3000, "localhost", () => {
  console.log("Server running at http://localhost:3000/");
});

The code above uses the promise-based parse() method to process the form’s data.

By default, formidable saves uploaded files in your computer’s temporary folder. You can change this setting if needed. The following section explains how.

How to Specify Where Formidable Should Save the Uploaded Files

The formidable() method takes an object that lets you specify the directory for saving uploaded files.

Here’s the syntax:

import formidable from "formidable";

const form = formidable({ uploadDir: "./folder/to/save/uploads" });

Here’s an example:

import formidable from "formidable";

const form = formidable({ uploadDir: "./" });

The code above tells Formidable to save uploaded files in the current directory.

Tip

The current directory is the folder where your source file is located. For example, if your source file is form-server.js, the current directory is the folder that contains form-server.js.

Here’s another example:

import formidable from "formidable";

const form = formidable({ uploadDir: "./uploads" });

The code above tells Formidable to save uploaded files in the uploads folder inside the current directory.

Tip

• Make sure the uploadDir you specify exists. If it does not, Formidable will discard the uploaded files without showing an error, unless you implement your own error handling.
• You can also use the fs.rename() method to move the uploaded file to a different location.