TypeScript Tutorial: Building a Simple Web-Based File Uploader

Written by

learnmodernjavascript

in

In the digital age, the ability to upload files to a web server is a fundamental requirement for many applications. From content management systems to social media platforms, file uploading is an essential feature. This tutorial will guide you through the process of creating a simple yet functional web-based file uploader using TypeScript, a powerful language that adds static typing to JavaScript. We’ll cover everything from the basics of HTML form creation to handling file uploads on the server-side, all while emphasizing clean code and best practices.

Why TypeScript?

TypeScript offers several advantages over plain JavaScript, especially for larger projects. These benefits include:

  • Improved Code Readability: TypeScript’s static typing makes your code easier to understand and maintain.
  • Early Error Detection: TypeScript catches type-related errors during development, reducing runtime surprises.
  • Enhanced Tooling: TypeScript provides better IDE support, including autocompletion and refactoring.
  • Scalability: TypeScript helps you build more complex applications with greater confidence.

By using TypeScript, you’ll be able to create a more robust and maintainable file uploader.

Setting Up the Project

Let’s get started by setting up our project. We’ll need Node.js and npm (Node Package Manager) installed on your system. If you don’t have them, download and install them from nodejs.org.

Create a new directory for your project and navigate into it using your terminal:

mkdir file-uploader-app
cd file-uploader-app

Initialize a new npm project:

npm init -y

Install TypeScript and a few other necessary packages:

npm install typescript @types/node express multer cors --save-dev

Here’s a breakdown of the packages:

  • typescript: The TypeScript compiler.
  • @types/node: Type definitions for Node.js.
  • express: A web application framework for Node.js.
  • multer: Middleware for handling `multipart/form-data`, primarily used for uploading files.
  • cors: Middleware for enabling Cross-Origin Resource Sharing (CORS).

Next, create a `tsconfig.json` file in your project root. This file tells the TypeScript compiler how to compile your code. You can generate a basic one using the following command:

npx tsc --init

This will create a `tsconfig.json` file. You might want to adjust some of the settings, such as the output directory (`outDir`) and the source directory (`rootDir`). A common setup is to have your TypeScript files in a `src` directory and the compiled JavaScript files in a `dist` directory. Here’s a sample `tsconfig.json`:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

Creating the HTML Form

Now, let’s create the HTML form that will allow users to select and upload files. Create an `index.html` file in your project root:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>File Uploader</title>
</head>
<body>
    <h1>File Uploader</h1>
    <input type="file" id="fileInput" multiple>
    <button onclick="uploadFiles()">Upload</button>
    <div id="status"></div>
    <script src="./dist/index.js"></script>
</body>
</html>

This HTML form includes:

  • An `input` element of type “file” with the `multiple` attribute, allowing users to select multiple files.
  • A button to trigger the upload process.
  • A `div` with the id “status” to display upload status messages.

Writing the TypeScript Code (Client-Side)

Let’s write the TypeScript code that will handle the file selection and upload process. Create a `src/index.ts` file:

const fileInput = document.getElementById('fileInput') as HTMLInputElement;
const statusDiv = document.getElementById('status') as HTMLDivElement;

async function uploadFiles() {
  if (!fileInput.files || fileInput.files.length === 0) {
    statusDiv.innerText = 'Please select a file.';
    return;
  }

  const files = Array.from(fileInput.files);

  for (const file of files) {
    try {
      const formData = new FormData();
      formData.append('file', file);

      statusDiv.innerText = `Uploading ${file.name}...`;

      const response = await fetch('/upload', {
        method: 'POST',
        body: formData,
      });

      if (response.ok) {
        statusDiv.innerText = `${file.name} uploaded successfully!`;
      } else {
        statusDiv.innerText = `Error uploading ${file.name}: ${response.statusText}`;
      }
    } catch (error) {
      statusDiv.innerText = `Error uploading ${file.name}: ${error}`;
    }
  }
}

Let’s break down this code:

  • We get references to the file input element and the status div.
  • The `uploadFiles()` function is triggered when the upload button is clicked.
  • It checks if any files have been selected.
  • It iterates through the selected files.
  • For each file, it creates a `FormData` object and appends the file to it.
  • It sends a POST request to the `/upload` endpoint (we’ll create this on the server-side).
  • It updates the status div to show the upload progress and any errors.

To compile the TypeScript code, run the following command in your terminal:

tsc

This will create a `dist/index.js` file, which is the compiled JavaScript code that the HTML file will use. Make sure your `index.html` file references this compiled JavaScript file.

Writing the TypeScript Code (Server-Side)

Now, let’s create the server-side code to handle the file uploads. Create a `src/server.ts` file:

import express from 'express';
import multer from 'multer';
import cors from 'cors';
import path from 'path';

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

app.use(cors()); // Enable CORS for all origins

// Configure multer for file uploads
const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, 'uploads/'); // Specify the upload directory
  },
  filename: (req, file, cb) => {
    cb(null, Date.now() + path.extname(file.originalname)); // Generate unique filename
  },
});

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

app.use(express.static('public')); // Serve static files (e.g., HTML, CSS, JS)

app.post('/upload', upload.array('file'), (req, res) => {
  if (!req.files || req.files.length === 0) {
    return res.status(400).send('No files were uploaded.');
  }

  const files = req.files as Express.Multer.File[];
  const fileNames = files.map(file => file.filename);
  res.status(200).send({ message: 'Files uploaded successfully!', fileNames });
});

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

Let’s go through this server-side code:

  • We import the necessary modules: `express`, `multer`, `cors`, and `path`.
  • We create an Express application.
  • We enable CORS to allow requests from any origin (for development). In a production environment, you should restrict this to the specific origins you trust.
  • We configure `multer` to handle file uploads. `multer.diskStorage` specifies where to store the uploaded files (the `uploads/` directory) and how to name them (using a timestamp and the original file extension). Make sure the `uploads/` directory exists or the server will fail.
  • We define a POST route `/upload` that handles file uploads. The `upload.array(‘file’)` middleware processes the incoming files. The `’file’` argument specifies the field name in the `FormData` object used in the client-side code.
  • We send a success response back to the client, including the uploaded file names.
  • We start the server and listen on port 3000.

To compile the server-side code, run the following command in your terminal:

tsc

This will compile the `src/server.ts` file into a `dist/server.js` file.

Running the Application

Now that we’ve written both the client and server-side code, let’s run the application. First, make sure you have the compiled JavaScript files ( `dist/index.js` and `dist/server.js`). You can compile the TypeScript files by running `tsc` in your terminal, in the project root directory.

To start the server, you can use `node dist/server.js` in your terminal. This will start the server and make it listen for incoming requests. You may need to install `ts-node` globally to run the server directly from the TypeScript file. If so, run `npm install -g ts-node`. Then you can use `ts-node src/server.ts`

Open your `index.html` file in a web browser. You should see the file uploader interface. Select one or more files and click the “Upload” button. The status messages will indicate the progress of the upload.

The uploaded files will be saved in the `uploads/` directory (created during the setup of multer). Make sure you have created this directory in the project root.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to fix them:

  • CORS Issues: If you’re encountering CORS errors, make sure you’ve enabled CORS on the server-side. The `cors()` middleware in the server code handles this. For production, restrict the origins allowed.
  • File Path Issues: Double-check the file paths in your HTML, TypeScript code, and the `multer` configuration. Make sure they are correct relative to the project root.
  • Missing Dependencies: Ensure you’ve installed all the necessary dependencies using npm. Run `npm install` in your project directory if you encounter errors related to missing modules.
  • Incorrect File Input Field Name: The `upload.array(‘file’)` middleware on the server-side must match the name of the field you are appending to the `FormData` on the client-side.
  • Server Not Running: Verify that your server is running and listening on the correct port. Check the console output for any error messages.
  • Incorrect File Permissions: Ensure the server process has the necessary permissions to write to the `uploads/` directory.
  • Missing Uploads Directory: The `uploads/` directory must exist in your project root before you run the server. The server does not create it automatically.

Enhancements and Further Steps

Here are some ways to enhance this simple file uploader:

  • Progress Bar: Add a progress bar to visually indicate the upload progress for each file.
  • File Size Validation: Implement file size validation on both the client and server-side to prevent large files from being uploaded.
  • File Type Validation: Restrict the allowed file types to ensure only specific file types are uploaded (e.g., images, documents).
  • Error Handling: Implement more robust error handling, including displaying more informative error messages to the user.
  • Security: Implement security measures such as input validation and sanitization to prevent potential security vulnerabilities.
  • User Interface: Improve the user interface with better styling and user experience.
  • Database Integration: Store file metadata (filename, size, upload date) in a database.
  • Cloud Storage: Integrate with cloud storage services (e.g., AWS S3, Google Cloud Storage) for more scalable and reliable file storage.

Summary / Key Takeaways

In this tutorial, we’ve successfully built a basic web-based file uploader using TypeScript, Express.js, and Multer. We covered the essential steps, from setting up the project and creating the HTML form to writing the client and server-side code. You’ve learned how to handle file uploads, manage file storage, and display upload status messages. Remember to address CORS issues, validate file types and sizes, and implement robust error handling in your production applications. By following these steps and exploring the enhancements, you can create a versatile and efficient file uploader tailored to your specific needs.

FAQ

  1. Why use TypeScript for this project? TypeScript provides type safety, which helps prevent errors and makes the code more maintainable, especially as the project grows.
  2. How do I handle different file types? You can use the `fileFilter` option in `multer` to validate file types on the server-side. On the client-side, you can use the `accept` attribute in the `<input type=”file”>` tag to restrict file types.
  3. How can I improve security? Implement input validation on both the client and server-side to prevent malicious file uploads. Consider using a content security policy (CSP) and regularly update your dependencies.
  4. What are some alternatives to Multer? Other popular file upload middleware for Node.js include Busboy and formidable. Multer is a good choice for its simplicity and ease of use.
  5. How do I deploy this application? You can deploy your application to a platform like Heroku, Netlify, or AWS. You’ll need to configure your deployment environment to run the server-side code and serve the static files.

Building a file uploader is a great learning experience, providing a solid foundation for understanding web development concepts. This simple example can be expanded into a powerful tool, ready to be integrated into any project where file management is required. Consider the various enhancements, and your file uploader will quickly become a valuable asset. The journey of learning and improving never truly ends, and each project provides a chance to enhance your skills and understanding of the ever-evolving world of web development.

More posts