TypeScript Tutorial: Building a Simple File Upload Application

Written by

learnmodernjavascript

in

In the world of web development, the ability to upload files is a fundamental feature. Whether it’s allowing users to share images, submit documents, or manage any type of media, file uploads are a common requirement. Building a file upload application from scratch can seem daunting, but with TypeScript, we can create a robust and type-safe solution. This tutorial will guide you through the process of building a simple file upload application using TypeScript, explaining each step in detail.

Why TypeScript for File Uploads?

TypeScript brings several benefits to the table when building file upload applications:

  • Type Safety: TypeScript’s static typing helps catch errors during development, before runtime. This is particularly helpful when dealing with file data, which can often be tricky to handle.
  • Improved Code Readability: Types make your code more understandable and easier to maintain.
  • Enhanced Developer Experience: TypeScript provides excellent tooling support, including autocompletion and error checking, which speeds up development.
  • Maintainability: As your application grows, TypeScript helps you manage complexity more effectively.

Prerequisites

Before we begin, make sure you have the following installed:

  • Node.js and npm (or yarn): Used for package management and running the application.
  • A text editor or IDE: Such as VS Code, Sublime Text, or WebStorm.
  • Basic understanding of HTML, CSS, and JavaScript: Familiarity with these technologies is essential.

Setting Up the Project

Let’s start by setting up our project. Open your terminal and create a new project directory:

mkdir file-upload-app
cd file-upload-app

Initialize a new Node.js project:

npm init -y

Install TypeScript and a few other necessary packages:

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

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 configuration using the TypeScript compiler:

npx tsc --init --rootDir src --outDir dist --esModuleInterop --resolveJsonModule --lib es6 --module commonjs

This command creates a tsconfig.json file with some sensible defaults. You might want to modify it to suit your needs, but the generated file is a good starting point. Key settings to note:

  • rootDir: Specifies the root directory of your TypeScript source files (e.g., “src”).
  • outDir: Specifies the output directory for the compiled JavaScript files (e.g., “dist”).
  • esModuleInterop: Enables interoperability between CommonJS and ES modules.
  • resolveJsonModule: Allows you to import JSON files.
  • lib: Specifies the JavaScript library files to be included (e.g., “es6”).
  • module: Specifies the module system to be used (e.g., “commonjs”).

Project Structure

Let’s create a basic project structure:

file-upload-app/
├── src/
│   ├── index.ts
│   └── routes.ts
├── dist/
├── node_modules/
├── tsconfig.json
├── package.json
└── .gitignore

In your .gitignore file, add:


node_modules
dist

Writing the Backend (Node.js with Express and Multer)

Now, let’s write the backend using Node.js, Express, and Multer. Create the file src/index.ts:

import express, { Request, Response } from 'express';
import cors from 'cors';
import { uploadRouter } from './routes';

const app = express();
const port = process.env.PORT || 3000;

app.use(cors()); // Enable CORS for all origins (for development - adjust in production)
app.use(express.json()); // Middleware to parse JSON request bodies

app.use('/api/upload', uploadRouter);

app.get('/', (req: Request, res: Response) => {
  res.send('File Upload Application');
});

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

Next, create src/routes.ts:

import express, { Request, Response } from 'express';
import multer from 'multer';
import path from 'path';

const router = express.Router();

// Configure Multer for file uploads
const storage = multer.diskStorage({
  destination: (req, file, cb) => {
    cb(null, 'uploads/'); // Specify the upload directory
  },
  filename: (req, file, cb) => {
    const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1e9);
    const ext = path.extname(file.originalname);
    cb(null, file.fieldname + '-' + uniqueSuffix + ext);
  },
});

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

router.post('/', upload.single('file'), (req: Request, res: Response) => {
  try {
    if (!req.file) {
      return res.status(400).send({ message: 'No file uploaded.' });
    }

    // Access file information using req.file
    const { originalname, filename, path, size, mimetype } = req.file;

    res.status(200).send({
      message: 'File uploaded successfully!',
      originalname,
      filename,
      path,
      size,
      mimetype,
    });
  } catch (error: any) {
    console.error(error);
    res.status(500).send({ message: 'Error uploading file.', error: error.message });
  }
});

export { router as uploadRouter };

Let’s break down the code:

  • Import Statements: We import the necessary modules: express, multer, and path.
  • Multer Configuration:
    • storage: This object configures where the uploaded files will be stored. We use multer.diskStorage to save files to the file system.
    • destination: A function that determines the upload directory. Here, we specify an “uploads/” directory. Make sure to create this directory in your project root.
    • filename: A function that determines the filename of the uploaded file. We generate a unique filename to avoid conflicts.
  • Multer Middleware: upload = multer({ storage: storage }) creates a Multer instance. The upload.single('file') middleware handles the file upload. The ‘file’ argument specifies the name of the input field in your HTML form.
  • Route Handler: The POST route at /api/upload handles the file upload.
    • req.file: Multer adds a file property to the request object, containing information about the uploaded file.
    • Error Handling: Includes a try-catch block to handle potential errors during the upload process.

Creating the Frontend (HTML and JavaScript)

Now, let’s create a simple HTML form and JavaScript to upload the file. Create an index.html file in the 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 Upload</title>
  <style>
    body {
      font-family: sans-serif;
    }
    #upload-form {
      margin: 20px;
    }
    input[type="file"] {
      margin-bottom: 10px;
    }
    button {
      padding: 10px 20px;
      background-color: #4CAF50;
      color: white;
      border: none;
      cursor: pointer;
    }
    #status {
      margin-top: 20px;
      padding: 10px;
      border: 1px solid #ccc;
    }
  </style>
</head>
<body>
  <div id="upload-form">
    <h2>File Upload</h2>
    <input type="file" id="fileInput" name="file"><br>
    <button onclick="uploadFile()">Upload</button>
    <div id="status"></div>
  </div>

  <script>
    async function uploadFile() {
      const fileInput = document.getElementById('fileInput') as HTMLInputElement;
      const file = fileInput.files?.[0];
      const statusDiv = document.getElementById('status') as HTMLDivElement;

      if (!file) {
        statusDiv.innerText = 'Please select a file.';
        return;
      }

      const formData = new FormData();
      formData.append('file', file);

      try {
        statusDiv.innerText = 'Uploading...';
        const response = await fetch('http://localhost:3000/api/upload', {
          method: 'POST',
          body: formData,
        });

        if (!response.ok) {
          throw new Error(`Upload failed: ${response.status} - ${await response.text()}`);
        }

        const data = await response.json();
        statusDiv.innerText = `Upload successful!nFilename: ${data.filename}nPath: ${data.path}nSize: ${data.size} bytesnMIME Type: ${data.mimetype}`;
      } catch (error: any) {
        statusDiv.innerText = `Upload failed: ${error.message}`;
      }
    }
  </script>
</body>
</html>

Let’s break down the HTML and JavaScript:

  • HTML Form: A simple form with a file input field and an upload button.
  • JavaScript (uploadFile function):
    • Gets the selected file from the input.
    • Creates a FormData object to send the file to the server.
    • Uses fetch to send a POST request to the /api/upload endpoint.
    • Handles the response, displaying success or error messages.

Running the Application

To run the application, first, compile the TypeScript code:

npm run build

Add this script to your package.json file, within the “scripts” section:


"build": "tsc"

Next, start the server:

npm start

Add this script to your package.json file, within the “scripts” section:


  "start": "node dist/index.js"

Open index.html in your browser. You should see the file upload form. Select a file and click the “Upload” button. Check your console for any errors. If everything works correctly, you should see a success message, and the uploaded file should be saved in the “uploads/” directory in your project.

Common Mistakes and How to Fix Them

Here are some common mistakes and how to fix them:

  • CORS Issues: If you’re running the frontend and backend on different ports, you might encounter CORS errors. Make sure your backend has CORS enabled (as shown in the code) or configure it more specifically for your frontend’s origin. In a production environment, you should restrict the allowed origins for security.
  • Incorrect File Path: Double-check the path to your uploads directory in your Multer configuration. Make sure it exists and that the server has write permissions to it.
  • Missing enctype (HTML Form): While not strictly necessary when using FormData and fetch, if you were using a traditional form submission, ensure your HTML form has the correct enctype="multipart/form-data" attribute. We are not using a form submission, so this is not required in our case, but good to know.
  • Incorrect Input Field Name: The upload.single('file') middleware in your backend expects a file input field named “file”. Make sure your HTML input field has the correct name="file" attribute.
  • File Size Limits: By default, Multer has a file size limit. You can configure this in the Multer options. For example, to set a maximum file size of 2MB: 
    const upload = multer({ 
  storage: storage,
  limits: {
    fileSize: 2 * 1024 * 1024, // 2MB in bytes
  }
});
  • Incorrect TypeScript Compilation: Ensure that your tsconfig.json is correctly configured, especially the rootDir and outDir options. Also, make sure you’re running the build process before starting the server.
  • Missing Uploads Directory: Ensure the “uploads” directory exists in your project root before running the application.

Advanced Features and Considerations

Here are some advanced features you can consider adding to your file upload application:

  • File Type Validation: Implement file type validation to ensure only allowed file types are uploaded. You can check the mimetype property of the req.file object.
  • Progress Bar: Add a progress bar to the frontend to show the upload progress to the user.
  • Error Handling: Implement more robust error handling, providing more informative error messages to the user.
  • Security:
    • Input Sanitization: Sanitize any user-provided data to prevent security vulnerabilities.
    • File Name Sanitization: Sanitize the file names to prevent malicious file uploads.
    • Authentication/Authorization: Implement authentication and authorization to restrict file uploads to authorized users.
  • Storage Options: Instead of storing files locally, consider using cloud storage services like AWS S3, Google Cloud Storage, or Azure Blob Storage.
  • File Compression/Optimization: Compress or optimize uploaded images to reduce storage space and improve performance.
  • Database Integration: Store file metadata (filename, path, size, etc.) in a database for easier management.

Summary / Key Takeaways

This tutorial demonstrated how to build a basic file upload application using TypeScript, Node.js, Express, and Multer. We covered setting up the project, writing the backend with file storage, and creating a simple frontend. You learned how to handle file uploads, access file information, and handle potential errors. By following these steps, you can create a solid foundation for more complex file upload functionalities in your web applications. Remember to always prioritize security and user experience as you build out more advanced features. This example serves as a starting point, and you can customize and extend it to meet your specific requirements. Consider the advanced features discussed to further enhance your file upload application, making it more robust and user-friendly. Always validate and sanitize data to ensure the security of your application.

FAQ

1. How do I handle multiple file uploads?

To handle multiple file uploads, use upload.array('files', maxCount) in your backend. In your HTML, use a file input with the multiple attribute. The `files` argument in upload.array() should match the `name` attribute of your file input. `maxCount` specifies the maximum number of files that can be uploaded.

2. How can I restrict file types?

You can restrict file types by checking the mimetype property of the req.file object in your backend. For example, to allow only images, you can check if req.file.mimetype.startsWith('image/').

3. How do I display a progress bar during file upload?

To display a progress bar, you’ll need to use the `XMLHttpRequest` API or the `fetch` API. Listen to the `progress` event on the `XMLHttpRequest` or use the `onprogress` event on the `fetch` API to get the upload progress. Update the progress bar’s width or value based on the `loaded` and `total` properties of the event object.

4. What are some best practices for file uploads in production?

In production, you should use cloud storage services like AWS S3 for scalability and reliability. Also, implement proper security measures, including input validation, file type validation, and authentication/authorization. Consider using a Content Delivery Network (CDN) to serve files efficiently.

Wrapping Up

Creating a file upload application with TypeScript provides a strong foundation for handling files in your web projects. By leveraging the type safety and features of TypeScript, you can build a more robust and maintainable application. Remember to consider security and user experience as you integrate this functionality into your projects. This approach ensures a smoother and more secure experience for your users, and a more manageable codebase for you as the developer. The principles demonstrated here can be applied to a wide range of file handling scenarios, making this a valuable skill in modern web development.

More posts