Handling file uploads from a client side application (e.g. an Ionic application) to a backend server (e.g. Node/Express/NestJS) is quite different to using POST requests to send text data. It may look quite similar on the front end, as a file input looks more or less the same as any other HTML input:

<input type="file" />

You might expect that you could just POST this data using a standard HTTP request to a server and retrieve the file in the same way that you would retrieve any other value from a form.

However, this is not how file uploads works. As you can probably imagine, sending text values to a server like a username or password is quite quick/easy and would be instantly available for the server to access. A file could be arbitrarily large, and if we want to send a 3GB video along with our POST request then it is going to take some time for all of those bytes to be sent over the network.

In this tutorial, we will be using an Ionic application as the front end client, and a Node/Express server as the backend to demonstrate these concepts. I have also published another tutorial that covers using NestJS to handle file uploads on the backend. Although we are using a specific tech stack here, the basic concepts covered apply quite generally in other contexts.

NOTE: This tutorial will be focusing on uploading files through a standard file input on the web. We will be covering handling native file uploads (e.g. from the users Photo gallery in an Ionic application that is running natively on iOS/Android) in another tutorial.

Not interested in the theory? Jump straight to the example. This tutorial will include examples for Ionic/StencilJS, Ionic/Angular, and Ionic/React.

The Role of Multipart Form Data

If you are using a standard HTML form tag to capture input and POST it to a server (which we won’t be doing) then you will need to set its enctype (encoding type) to multipart/form-data:

<form action="http://localhost:3000/upload" method="post" enctype="multipart/form-data">
  <input type="file" name="photo" />
</form>

This is just one way to encode the form data that is to be sent off to some server. The default encoding type for a form is application/x-www-form-urlencoded but if we want to upload a file using the file input type then we need to set the enctype to multipart/form-data. This encoding type is not as efficient as x-www-form-urlencoded but if we use multipart/form-data then it won’t encode characters which means the files being uploaded won’t have their data corrupted by the encoding process.

Using the Form Data API

As I mentioned, we are not going to be using a standard HTML <form> with an action and enctype. This is common in the context of Ionic/Angular/React/StencilJS applications as we commonly implement our own form logic and handle firing off our own HTTP requests to submit form data (rather than setting the action of the form and having the user click a <input type="submit"> button).

Since we are just using form input elements as a way to capture data, rather than using an HTML form to actually submit the data for us, we need a way to send that captured data along with the HTTP request we trigger at some point. This is easy enough with simple text data, as we can just attach it directly to the body manually, e.g:

const data = {
    comment: 'hello',
    author: 'josh'
};

let response = await fetch("https://someapi.com/comments", {
    method: 'POST',
    body: JSON.stringify(data),
    headers: {
        'Content-Type': 'application/json'
    }
});

In this scenario, we could just replace hello and josh with whatever data the user entered into the form inputs (exactly how this is achieved will depend on the framework being used).

If you would like more information on sending POST requests with the Fetch API you can read: HTTP Requests in StencilJS with the Fetch API. This is a good option if you are using StencilJS or React, but if you are using Angular you would be better off using the built-in HttpClient.

But how do we handle adding files to the body of the HTTP request?

We can’t just add files to the body of the request as we would with simple text values. This is where the FormData API comes in. The FormData API allows us to dynamically create form data that we can send via an HTTP request, without actually needing to use an HTML <form>. The best part is that the form data created will be encoded the same way as if we had used a form with an enctype of multipart/form-data which is exactly what we want to upload files.

All you would need to do is listen for a change event on the file input fields, e.g. in StencilJS/React:

<input type="file" onChange={ev => this.onFileChange(ev)}></input>

or Angular:

<input type="file" (change)="onFileChange($event)" />

and then pass that event to some method that will make the data available to whatever is building your form data for submission (either immediately or later). With StencilJS this would look like:

uploadPhoto(fileChangeEvent){
  // Get a reference to the file that has just been added to the input
  const photo = fileChangeEvent.target.files[0];

  // Create a form data object using the FormData API
  let formData = new FormData();

  // Add the file that was just added to the form data
  formData.append("photo", photo, photo.name);

  // POST formData to server using Fetch API
}

or with React:

  const uploadPhoto = (fileChangeEvent) => {

    // Get a reference to the file that has just been added to the input
    const photo = fileChangeEvent.target.files[0];

    // Create a form data object using the FormData API
    let formData = new FormData();

    // Add the file that was just added to the form data
    formData.append("photo", photo, photo.name);

    // POST formData to server using Fetch API 
  };

or with Angular:

  uploadPhoto(fileChangeEvent) {
    // Get a reference to the file that has just been added to the input
    const photo = fileChangeEvent.target.files[0];

    // Create a form data object using the FormData API
    let formData = new FormData();

    // Add the file that was just added to the form data
    formData.append("photo", photo, photo.name);

    // POST formData to server using HttpClient
  }

If you didn’t want to submit the form immediately after detecting the change event, you could store the value of fileChangeEvent.target.files[0] somewhere until you are ready to use it (e.g. in a member variable in Angular or StencilJS, or with a useRef in React). Keep in mind that you do specifically need to store the result of a change/submit event to get a reference to the File, attempting to get the current value of the form control when you need to use it (as you would with other standard <input> fields) won’t work, it will just return:

C:\fakepath\

Which is a security feature implemented by browsers to prevent the filesystem structure of the users machine being exposed through JavaScript.

#ionic #programming #developer #web-development