TypeScript Tutorial: Building a Simple Interactive Web-Based PDF Viewer

Written by

learnmodernjavascript

in

In today’s digital world, the ability to view and interact with PDF documents directly within a web browser is a crucial feature for many applications. Imagine you’re building a document management system, an e-learning platform, or even a simple personal blog where you want to display downloadable guides. Instead of forcing users to download PDFs and open them in separate applications, wouldn’t it be great to provide a seamless, in-browser viewing experience? This tutorial will guide you through the process of building a simple, interactive web-based PDF viewer using TypeScript. We’ll explore the core concepts, libraries, and techniques needed to create a functional and user-friendly viewer, empowering you to integrate PDF viewing capabilities into your web projects.

Why Build a Web-Based PDF Viewer?

There are several compelling reasons to build a web-based PDF viewer:

  • Improved User Experience: Users can view documents instantly without leaving the browser, eliminating the need for downloads and external applications.
  • Enhanced Accessibility: Web-based viewers can be designed with accessibility in mind, ensuring compatibility with screen readers and other assistive technologies.
  • Cross-Platform Compatibility: Web viewers work consistently across different operating systems and devices, providing a unified experience for all users.
  • Increased Engagement: Interactive features, such as annotations or search, can be added to enhance user engagement with the documents.

Prerequisites

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

  • Node.js and npm (or yarn): You’ll need Node.js and npm (Node Package Manager) or yarn to manage project dependencies. You can download them from the official Node.js website.
  • TypeScript: Install TypeScript globally using npm: npm install -g typescript
  • A Code Editor: A code editor like Visual Studio Code (VS Code), Sublime Text, or Atom is recommended for writing and editing your code.
  • Basic HTML, CSS, and JavaScript knowledge: Familiarity with HTML, CSS, and JavaScript is helpful, although the tutorial will explain the TypeScript-specific aspects.

Setting Up the Project

Let’s start by setting up our project. Create a new directory for your project and navigate into it using your terminal. Then, initialize a new npm project:

mkdir pdf-viewer-tutorial
cd pdf-viewer-tutorial
npm init -y

This command creates a package.json file in your project directory. Next, we’ll install the necessary dependencies:

npm install pdfjs-dist --save-dev

Here, we are installing pdfjs-dist, the official PDF.js library. This library provides the core functionalities for parsing and rendering PDF documents in the browser. Next, initialize a TypeScript configuration file:

npx tsc --init

This creates a tsconfig.json file, which configures the TypeScript compiler. You can customize this file based on your project’s needs. For a basic setup, the default configuration should suffice. Finally, create the following files in your project directory:

  • index.html: The main HTML file for your viewer.
  • src/index.ts: The main TypeScript file where we’ll write our viewer logic.
  • style.css: For styling the viewer.

Building the HTML Structure (index.html)

Open index.html and add the basic HTML structure:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Simple PDF Viewer</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div id="pdf-container">
        <canvas id="pdf-canvas"></canvas>
    </div>
    <script src="./dist/index.js"></script>
</body>
</html>

This HTML sets up a basic page with a <canvas> element, which we will use to render the PDF pages. It also includes the necessary CSS and JavaScript files.

Styling the Viewer (style.css)

Now, let’s add some basic styling to style.css:

#pdf-container {
    width: 100%;
    overflow: auto;
}

#pdf-canvas {
    border: 1px solid #ccc;
    margin: 10px;
}

This CSS provides a basic layout for the PDF viewer, including a container and a canvas for rendering the PDF pages.

Writing the TypeScript Logic (src/index.ts)

This is where the core logic of our PDF viewer resides. Open src/index.ts and start by importing the necessary modules from pdfjs-dist:

import * as pdfjsLib from 'pdfjs-dist';
// If you are using a bundler (like webpack or Parcel), you might need to import the worker:
import pdfjsWorker from 'pdfjs-dist/build/pdf.worker.entry';

pdfjsLib.GlobalWorkerOptions.workerSrc = pdfjsWorker;

Next, define the necessary variables and functions to load and render the PDF:

const pdfContainer = document.getElementById('pdf-container') as HTMLDivElement;
const canvas = document.getElementById('pdf-canvas') as HTMLCanvasElement;
const ctx = canvas.getContext('2d') as CanvasRenderingContext2D;

let pdfDoc: pdfjsLib.PDFDocumentProxy | null = null;
let currentPage = 1;

async function loadPdf(pdfUrl: string) {
    try {
        pdfDoc = await pdfjsLib.getDocument(pdfUrl).promise;
        renderPage(currentPage);
    } catch (error) {
        console.error('Error loading PDF:', error);
        alert('Error loading PDF. Please check the console for details.');
    }
}

async function renderPage(pageNum: number) {
    if (!pdfDoc) return;

    try {
        const page = await pdfDoc.getPage(pageNum);
        const viewport = page.getViewport({ scale: 1.5 }); // Adjust scale as needed

        canvas.width = viewport.width;
        canvas.height = viewport.height;

        const renderContext = {
            canvasContext: ctx,
            viewport: viewport,
        };
        await page.render(renderContext);
    } catch (error) {
        console.error('Error rendering page:', error);
        alert('Error rendering page. Please check the console for details.');
    }
}

Here’s a breakdown of the code:

  • We import the pdfjs-dist library.
  • We get references to the HTML elements (container and canvas).
  • We define variables to hold the PDF document and the current page number.
  • The loadPdf function loads the PDF from a URL and calls renderPage to display the first page.
  • The renderPage function gets a specific page, sets the canvas dimensions, and renders the page onto the canvas using the pdf.js library.

Now, let’s add a function to handle navigation:

function setupNavigation() {
    const prevButton = document.createElement('button');
    prevButton.textContent = 'Previous';
    prevButton.addEventListener('click', () => {
        if (pdfDoc && currentPage > 1) {
            currentPage--;
            renderPage(currentPage);
        }
    });

    const nextButton = document.createElement('button');
    nextButton.textContent = 'Next';
    nextButton.addEventListener('click', () => {
        if (pdfDoc && currentPage < pdfDoc.numPages) {
            currentPage++;
            renderPage(currentPage);
        }
    });

    const navigationContainer = document.createElement('div');
    navigationContainer.style.textAlign = 'center';
    navigationContainer.appendChild(prevButton);
    navigationContainer.appendChild(nextButton);
    pdfContainer.appendChild(navigationContainer);
}

This code creates “Previous” and “Next” buttons and attaches event listeners to them. When clicked, these buttons update the currentPage variable and call the renderPage function to display the appropriate page.

Finally, call the functions to load the PDF and set up navigation. Also, add the initial PDF URL to load. Your complete src/index.ts file should look like this:

import * as pdfjsLib from 'pdfjs-dist';
import pdfjsWorker from 'pdfjs-dist/build/pdf.worker.entry';

pdfjsLib.GlobalWorkerOptions.workerSrc = pdfjsWorker;

const pdfContainer = document.getElementById('pdf-container') as HTMLDivElement;
const canvas = document.getElementById('pdf-canvas') as HTMLCanvasElement;
const ctx = canvas.getContext('2d') as CanvasRenderingContext2D;

let pdfDoc: pdfjsLib.PDFDocumentProxy | null = null;
let currentPage = 1;

async function loadPdf(pdfUrl: string) {
    try {
        pdfDoc = await pdfjsLib.getDocument(pdfUrl).promise;
        renderPage(currentPage);
        setupNavigation();
    } catch (error) {
        console.error('Error loading PDF:', error);
        alert('Error loading PDF. Please check the console for details.');
    }
}

async function renderPage(pageNum: number) {
    if (!pdfDoc) return;

    try {
        const page = await pdfDoc.getPage(pageNum);
        const viewport = page.getViewport({ scale: 1.5 }); // Adjust scale as needed

        canvas.width = viewport.width;
        canvas.height = viewport.height;

        const renderContext = {
            canvasContext: ctx,
            viewport: viewport,
        };
        await page.render(renderContext);
    } catch (error) {
        console.error('Error rendering page:', error);
        alert('Error rendering page. Please check the console for details.');
    }
}

function setupNavigation() {
    const prevButton = document.createElement('button');
    prevButton.textContent = 'Previous';
    prevButton.addEventListener('click', () => {
        if (pdfDoc && currentPage > 1) {
            currentPage--;
            renderPage(currentPage);
        }
    });

    const nextButton = document.createElement('button');
    nextButton.textContent = 'Next';
    nextButton.addEventListener('click', () => {
        if (pdfDoc && currentPage < pdfDoc.numPages) {
            currentPage++;
            renderPage(currentPage);
        }
    });

    const navigationContainer = document.createElement('div');
    navigationContainer.style.textAlign = 'center';
    navigationContainer.appendChild(prevButton);
    navigationContainer.appendChild(nextButton);
    pdfContainer.appendChild(navigationContainer);
}

// Replace with your PDF URL
const pdfUrl = 'your-pdf-file.pdf'; // Or a URL to a PDF file
loadPdf(pdfUrl);

Replace 'your-pdf-file.pdf' with the URL of your PDF file. For testing, you can use a public PDF URL or place a PDF file in your project directory.

Compiling and Running the Application

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

tsc

This command will compile your TypeScript code into JavaScript and generate a dist/index.js file. Now, open index.html in your browser. You should see the first page of your PDF displayed on the canvas, along with the “Previous” and “Next” buttons. If the PDF doesn’t load, check the browser’s developer console for any error messages and ensure that your PDF URL is correct and accessible.

Common Mistakes and Troubleshooting

Here are some common mistakes and how to fix them:

  • Incorrect PDF URL: Double-check the PDF URL to ensure it is correct and accessible from your browser. Try using a publicly available PDF URL to test if the issue is with your PDF file.
  • CORS (Cross-Origin Resource Sharing) Issues: If you’re loading the PDF from a different domain, you might encounter CORS issues. Make sure the server hosting the PDF allows cross-origin requests. You can use a CORS proxy for testing.
  • Incorrect File Paths: Ensure that the file paths in your HTML (for the CSS and JavaScript files) are correct.
  • Canvas Not Found: Verify that the ID of the canvas element in your HTML matches the ID used in your TypeScript code.
  • Typo in Code: Carefully review your TypeScript code for any typos or syntax errors.
  • Missing Dependencies: Make sure you have installed all the required dependencies (pdfjs-dist) using npm.

Adding Enhancements

Once you have a basic PDF viewer, you can add various enhancements to improve its functionality and user experience. Here are some ideas:

  • Zooming: Implement zoom functionality to allow users to zoom in and out of the PDF pages. You can modify the scale when calling the getViewport method.
  • Page Navigation: Add page number input and go-to-page functionality for easy navigation.
  • Search: Integrate search functionality to enable users to search for text within the PDF.
  • Annotations: Allow users to add annotations (e.g., highlights, comments) to the PDF.
  • Loading Indicator: Display a loading indicator while the PDF is being loaded and rendered to provide feedback to the user.
  • Error Handling: Implement more robust error handling to catch and display informative error messages to the user.

Key Takeaways

  • You can build a web-based PDF viewer using the pdfjs-dist library and TypeScript.
  • The process involves loading the PDF, rendering pages onto a canvas, and adding navigation controls.
  • Proper error handling and user experience considerations are vital for a functional and user-friendly viewer.
  • Enhancements like zooming, page navigation, and search can further improve the viewer’s functionality.

FAQ

Q: Can I use this code with a different PDF library?

A: While this tutorial uses pdfjs-dist, you can adapt the code to work with other PDF libraries. However, the specific implementation details will vary depending on the chosen library.

Q: How do I handle large PDF files?

A: For large PDF files, consider optimizing the rendering process. You can use techniques like lazy loading (rendering pages as the user scrolls) and caching rendered pages to improve performance.

Q: What are the security considerations when displaying PDFs in a web application?

A: Be mindful of the source of the PDF files. Avoid displaying PDFs from untrusted sources, as they might contain malicious code. Always sanitize user input and implement appropriate security measures to protect your application.

Q: Can I add print functionality to the PDF viewer?

A: Yes, you can add a print button that uses the browser’s print functionality to print the PDF. You can also implement a custom printing solution using the pdfjs-dist library.

Q: How can I deploy the PDF viewer to a web server?

A: You can deploy the viewer to any web server. Make sure the server is configured to serve the HTML, CSS, JavaScript, and PDF files correctly. Consider using a build tool like Webpack or Parcel to bundle your code for production.

Building a web-based PDF viewer with TypeScript and the pdfjs-dist library is a practical skill that can significantly enhance your web development projects. By following the steps outlined in this tutorial, you can create a functional and interactive PDF viewer that provides a seamless user experience. Remember to experiment with enhancements like zooming, page navigation, and search to create a more feature-rich and user-friendly application. The ability to display and interact with PDFs directly within a web browser opens up a world of possibilities for document management, e-learning, and various other web applications. As you continue to develop your viewer, consider the user experience, accessibility, and security aspects to ensure that your application is both functional and safe. Embrace the power of TypeScript and the flexibility of web technologies to create innovative and engaging web solutions.

More posts