TypeScript Tutorial: Building a Simple Web-Based File Downloader

Written by

learnmodernjavascript

in

In today’s digital landscape, the ability to download files from a web application is a fundamental requirement. From retrieving documents and images to fetching software updates, the need for a reliable and user-friendly file downloader is ubiquitous. This tutorial will guide you through building a simple, yet effective, web-based file downloader using TypeScript. We’ll cover everything from setting up the project to handling user interactions and providing a seamless download experience. This project isn’t just about learning how to download files; it’s about understanding the core principles of web development with TypeScript, including how to interact with the browser’s API and manage asynchronous operations.

Why TypeScript for a File Downloader?

TypeScript offers several advantages when building web applications, especially when handling tasks like file downloads:

  • Type Safety: TypeScript’s static typing helps catch errors early in the development process. This is crucial for avoiding runtime issues, especially when dealing with file types and data structures.
  • Code Completion and Refactoring: TypeScript provides excellent code completion and refactoring capabilities, improving developer productivity and code maintainability.
  • Modern JavaScript Features: TypeScript supports the latest JavaScript features, allowing you to write cleaner and more modern code.
  • Scalability: TypeScript makes it easier to scale your application as it grows, thanks to its strong typing and modular design.

Project Setup

Let’s get started by setting up our project. We’ll use a basic HTML structure, TypeScript for our logic, and a simple server (Node.js with Express) to serve the files. First, create a new project directory and navigate into it using your terminal:

mkdir file-downloader-app
cd file-downloader-app

Next, initialize a new Node.js project:

npm init -y

Now, install TypeScript and other necessary dependencies:

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

Create a tsconfig.json file in your project root with the following configuration. This file tells the TypeScript compiler how to compile your code:

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

Create the following file structure:

file-downloader-app/
├── src/
│   ├── server.ts
│   ├── public/
│   │   ├── index.html
│   │   └── script.ts
├── dist/
├── package.json
├── tsconfig.json
└── .gitignore

Let’s create the basic HTML file (src/public/index.html):

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>File Downloader</title>
</head>
<body>
    <h1>File Downloader</h1>
    <button id="downloadButton">Download File</button>
    <script src="script.js"></script>
</body>
</html>

And the basic TypeScript file (src/public/script.ts):

const downloadButton = document.getElementById('downloadButton');

if (downloadButton) {
    downloadButton.addEventListener('click', () => {
        // Download logic will go here
        console.log('Download button clicked!');
    });
}

Finally, the server file (src/server.ts):

import express from 'express';
import path from 'path';

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

app.use(express.static(path.join(__dirname, 'public')));

// Serve a dummy file for download
app.get('/download', (req, res) => {
    const filePath = path.join(__dirname, '..', 'public', 'dummy.txt'); // Adjust path as needed
    res.download(filePath, 'downloaded_file.txt', (err) => {
        if (err) {
            console.error('Error sending file:', err);
            res.status(500).send('Error downloading file');
        }
    });
});

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

Now, let’s create a dummy file in the public directory (src/public/dummy.txt):

This is a dummy file for download.

Compile the TypeScript code:

npx tsc

Run the server:

node dist/server.js

Open your browser and navigate to http://localhost:3000. You should see the button. Clicking it currently logs a message to the console. We’ll implement the actual download logic next.

Implementing the Download Functionality

Now, let’s implement the core download functionality in our script.ts file. We’ll use the browser’s fetch API to make a request to our server, which will then serve the file for download. Update src/public/script.ts as follows:

const downloadButton = document.getElementById('downloadButton');

if (downloadButton) {
    downloadButton.addEventListener('click', () => {
        fetch('/download')
            .then(response => {
                if (!response.ok) {
                    throw new Error('Network response was not ok');
                }
                return response.blob();
            })
            .then(blob => {
                const url = window.URL.createObjectURL(blob);
                const a = document.createElement('a');
                a.href = url;
                a.download = 'downloaded_file.txt'; // Set the desired filename
                document.body.appendChild(a);
                a.click();
                document.body.removeChild(a);
                window.URL.revokeObjectURL(url);
            })
            .catch(error => {
                console.error('There was an error downloading the file:', error);
                alert('Download failed.  Check the console for details.');
            });
    });
}

Let’s break down this code:

  • Fetch Request: We use the fetch('/download') to make a GET request to our server’s download endpoint.
  • Error Handling: We check if the response is okay (status code in the 200-299 range). If not, we throw an error.
  • Blob Conversion: We convert the response to a Blob, which represents the file data.
  • ObjectURL Creation: We create a temporary URL for the Blob using window.URL.createObjectURL(blob).
  • Creating the Download Link: We create an anchor element (<a>) and set its href to the Blob URL. We also set the download attribute to specify the filename.
  • Triggering the Download: We append the anchor to the document body, simulate a click, and then remove the anchor.
  • Revoking the URL: After the download, we revoke the object URL to free up resources using window.URL.revokeObjectURL(url).
  • Error Handling (Catch): We catch any errors that occur during the process and log them to the console and alert the user.

Recompile the TypeScript code (npx tsc) and refresh your browser. Clicking the button should now trigger a download of the dummy.txt file.

Advanced Features: Progress Indicators and File Type Handling

Adding a Progress Indicator

To improve the user experience, let’s add a progress indicator. We can update the UI while the file is being downloaded. First, add an element to display the progress in your index.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>File Downloader</title>
</head>
<body>
    <h1>File Downloader</h1>
    <button id="downloadButton">Download File</button>
    <div id="progressContainer" style="display: none;">
        <progress id="progressBar" value="0" max="100"></progress>
        <span id="progressText">0%</span>
    </div>
    <script src="script.js"></script>
</body>
</html>

Next, update your script.ts to include progress tracking. Note that the fetch API doesn’t directly provide progress updates for the entire download process, but we can simulate progress to some extent. We can’t get precise progress for the initial request, but we can update the UI while the blob is being processed. Here’s how to do that:

const downloadButton = document.getElementById('downloadButton');
const progressContainer = document.getElementById('progressContainer');
const progressBar = document.getElementById('progressBar') as HTMLProgressElement;
const progressText = document.getElementById('progressText');

if (downloadButton && progressContainer && progressBar && progressText) {
    downloadButton.addEventListener('click', () => {
        progressContainer.style.display = 'block'; // Show the progress bar
        progressBar.value = 0;
        progressText.textContent = '0%';

        fetch('/download')
            .then(response => {
                if (!response.ok) {
                    throw new Error('Network response was not ok');
                }
                return response.blob();
            })
            .then(blob => {
                // Simulate progress (simplified for demonstration)
                progressBar.value = 50;  // Simulate some progress
                progressText.textContent = '50%';

                const url = window.URL.createObjectURL(blob);
                const a = document.createElement('a');
                a.href = url;
                a.download = 'downloaded_file.txt';
                document.body.appendChild(a);
                a.click();
                document.body.removeChild(a);
                window.URL.revokeObjectURL(url);

                progressBar.value = 100; // Indicate completion
                progressText.textContent = '100%';
                setTimeout(() => {  // Hide after a short delay
                    progressContainer.style.display = 'none';
                }, 1000);  // Hide after 1 second
            })
            .catch(error => {
                console.error('There was an error downloading the file:', error);
                alert('Download failed. Check the console for details.');
                progressContainer.style.display = 'none'; // Hide on error
            });
    });
}

In this updated code:

  • We get references to the progress bar and text elements.
  • We show the progress container when the download starts.
  • We simulate progress updates (50%, 100%) during the blob processing. In a real-world scenario, you might have to find a different approach to calculate the progress, depending on your needs. For example, if you were downloading a large file in chunks, you could track the progress more accurately.
  • We hide the progress container after a short delay (1 second) after the download completes or when an error occurs.

Recompile and test. You should see the progress bar appear and update during the download process.

Handling Different File Types

Our current implementation downloads a simple text file. To handle different file types, we need to consider several things:

  • Content-Type Header: The server should set the Content-Type header in the response to indicate the file type (e.g., application/pdf, image/jpeg, text/csv). This helps the browser handle the file correctly. In our server code (src/server.ts), we can set this header like this:
// ... inside the /download route
res.setHeader('Content-Type', 'text/plain'); // Or the appropriate MIME type
res.download(filePath, 'downloaded_file.txt', (err) => {
    // ... rest of the code
});
  • Filename Extension: The filename in the download attribute should match the file type to ensure the correct file extension is used.
  • File Extension Handling: The browser uses the file extension and the Content-Type header to determine how to handle the downloaded file. For example, a PDF will open in a PDF viewer, an image will be displayed, and a CSV file might be opened in a spreadsheet application.

Let’s modify our server to serve a PDF file. First, create a dummy PDF file (e.g., dummy.pdf) in the src/public directory. You can use any PDF file for testing. Then, update your server code in src/server.ts to serve the PDF:

import express from 'express';
import path from 'path';

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

app.use(express.static(path.join(__dirname, 'public')));

// Serve a PDF file for download
app.get('/download-pdf', (req, res) => {
    const filePath = path.join(__dirname, '..', 'public', 'dummy.pdf');

    res.setHeader('Content-Type', 'application/pdf'); // Set the correct MIME type
    res.download(filePath, 'downloaded_file.pdf', (err) => {
        if (err) {
            console.error('Error sending file:', err);
            res.status(500).send('Error downloading file');
        }
    });
});

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

Also, update your src/public/script.ts to trigger the PDF download. We’ll add another button for this:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>File Downloader</title>
</head>
<body>
    <h1>File Downloader</h1>
    <button id="downloadButton">Download Text File</button>
    <button id="downloadPdfButton">Download PDF File</button>
    <div id="progressContainer" style="display: none;">
        <progress id="progressBar" value="0" max="100"></progress>
        <span id="progressText">0%</span>
    </div>
    <script src="script.js"></script>
</body>
</html>

And then update src/public/script.ts:

const downloadButton = document.getElementById('downloadButton');
const downloadPdfButton = document.getElementById('downloadPdfButton');
const progressContainer = document.getElementById('progressContainer');
const progressBar = document.getElementById('progressBar') as HTMLProgressElement;
const progressText = document.getElementById('progressText');

function downloadFile(url: string, filename: string) {
    progressContainer.style.display = 'block';
    progressBar.value = 0;
    progressText.textContent = '0%';

    fetch(url)
        .then(response => {
            if (!response.ok) {
                throw new Error('Network response was not ok');
            }
            return response.blob();
        })
        .then(blob => {
            progressBar.value = 50;
            progressText.textContent = '50%';

            const url = window.URL.createObjectURL(blob);
            const a = document.createElement('a');
            a.href = url;
            a.download = filename;
            document.body.appendChild(a);
            a.click();
            document.body.removeChild(a);
            window.URL.revokeObjectURL(url);

            progressBar.value = 100;
            progressText.textContent = '100%';
            setTimeout(() => {
                progressContainer.style.display = 'none';
            }, 1000);
        })
        .catch(error => {
            console.error('There was an error downloading the file:', error);
            alert('Download failed. Check the console for details.');
            progressContainer.style.display = 'none';
        });
}

if (downloadButton) {
    downloadButton.addEventListener('click', () => {
        downloadFile('/download', 'downloaded_file.txt');
    });
}

if (downloadPdfButton) {
    downloadPdfButton.addEventListener('click', () => {
        downloadFile('/download-pdf', 'downloaded_file.pdf');
    });
}

In this example, we added a new button to trigger the PDF download. We also refactored the download logic into a function called downloadFile() to avoid code duplication. The key is to specify the correct URL and filename when calling the function. Recompile the TypeScript code and test the PDF download; it should open in your browser’s PDF viewer.

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

  • Incorrect File Paths: Double-check your file paths in both the server and the client-side code. A common issue is the server not being able to find the file to download.
  • CORS Issues: If you’re downloading files from a different domain, you might encounter CORS (Cross-Origin Resource Sharing) issues. Ensure your server is configured to handle CORS requests, or consider using a proxy.
  • Incorrect MIME Types: Make sure the Content-Type header is set correctly on the server. Incorrect MIME types can cause the browser to handle the file incorrectly or prevent it from downloading.
  • Filename Issues: The filename specified in the download attribute can sometimes be overridden by the server’s response headers. Ensure that the server’s Content-Disposition header (if present) allows the filename you want.
  • Network Errors: Check your browser’s developer console for any network errors that might be preventing the download.
  • Typographical Errors: Typos in your code can lead to unexpected behavior. Carefully check for any typos.

Key Takeaways

  • TypeScript’s Benefits: TypeScript enhances code quality, readability, and maintainability in web development projects.
  • Fetch API: The fetch API is the modern way to make HTTP requests in JavaScript and TypeScript.
  • Blob and URL.createObjectURL: Understanding how to work with Blobs and create object URLs is essential for handling file downloads.
  • Error Handling: Implement robust error handling to provide a better user experience and debug issues effectively.
  • Progress Indicators: Consider adding progress indicators for a more user-friendly download experience.

FAQ

Q: Can I download files from a different domain?

A: Yes, but you may need to configure CORS (Cross-Origin Resource Sharing) on the server serving the files. The server must include the appropriate headers to allow requests from your domain.

Q: How do I handle large file downloads?

A: For large files, consider using techniques such as chunked downloads or streaming. Chunked downloads involve downloading the file in smaller parts. Streaming allows you to send the file to the client as it’s being read from the server, improving efficiency.

Q: Why is my filename not being set correctly?

A: The browser’s behavior regarding the filename can be influenced by the server’s response headers, particularly the Content-Disposition header. Make sure the server is sending the correct Content-Disposition header or the download attribute in your HTML.

Q: How can I improve the security of my file downloader?

A: Always validate user input, especially the file names and paths. Implement proper authentication and authorization to restrict access to sensitive files. Consider using secure protocols (HTTPS) and regularly update your dependencies to patch vulnerabilities.

Conclusion

This guide provided a comprehensive approach to building a web-based file downloader using TypeScript. We explored the core concepts, from setting up the project and implementing the download functionality to adding advanced features like progress indicators and handling different file types. Through this project, you’ve gained valuable insights into working with the browser’s API, managing asynchronous operations, and enhancing the user experience. By understanding these principles, you’re well-equipped to tackle more complex web development tasks and create robust, user-friendly applications. Building a web-based file downloader is a practical skill and a stepping stone to developing more sophisticated web applications. The knowledge gained here can be applied to various projects, from creating a simple file sharing app to integrating file downloads into more complex systems. By continuously practicing and exploring new features, you can evolve your skills and become a proficient TypeScript developer.

More posts